831115 - Documentation errors in TelemetryStopwatch.jsm

Status: RESOLVED WORKSFORME

(Toolkit :: Telemetry, defect)

Description

[Richard Newman [:rnewman]]

Hit this reviewing Bug 828720.

TelemetryStopwatch.start() reads:

   * @param aHistogram a string which must be a valid histogram name
   *                   from TelemetryHistograms.h

That file doesn't exist.

stop() says:

   * @param aHistogram a string which must be a valid histogram name
   *                   from TelemetryHistograms.json


That file doesn't exist either.

As far as I can tell, the name must be present in toolkit/components/telemetry/Histograms.json, a file that is only mentioned in the Makefile.

It would be great if someone who knows what's actually going on would read through this file and make sure the docs match reality, and furthermore add some useful points:

* What happens if the histogram name is not present?
* What's the format of an entry in Histograms.json?

Comment 1

[Nathan Froyd [:froydnj]]

FWIW, TelemetryHistograms.h used to exist and then got removed in a Code Cleanup.

I agree that better documentation around this would be good.  Do you have any suggestions on where documentation of an entry in Histograms.json ought to live?

Comment 2

[Richard Newman [:rnewman]]

It looks like 

  https://developer.mozilla.org/en-US/docs/Performance/Adding_a_new_Telemetry_probe

is up-to-date, so I would simply suggest that Telemetry*.jsm have class-level comments pointing to MDN (e.g., "To add a new probe, go here:", and whatever else a developer touching this code might want to know), and correct javadocs for each method.

I'd rather have no docs than wrong docs, and I'd rather have a pointer to good docs than no docs! :D

Comment 3

[Chris H-C :chutten]

The documentation is current and up-to-date now.