1426453 - Documentation of nsITelemetry not up to date

Status: RESOLVED FIXED

(Toolkit :: Telemetry, defect, P3)

Description

[Aditya Bharti [:adbugger]]

User Agent: Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:57.0) Gecko/20100101 Firefox/57.0
Build ID: 20171129230835

Steps to reproduce:

Go to link: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsITelemetry


Actual results:

The page lists the method newHistogram, which was removed in bug 1288745. It is also missing other methods such as CanRecordReleaseData and related.

See also: bug 1288745, bug 1410907


Expected results:

nsITelemetry documentation should be up to date and reflect the file toolkit/components/telemetry/nsITelemetry.idl

Comment 1

[Georg Fritzsche [:gfritzsche]]

Thanks, good find.
Would you be interested in updating this page?

Comment 2

[Aditya Bharti [:adbugger]]

Sure, I'll update the page. For now, I'm working on extending the telemetry API as part of another bug. After that, I should have a better understanding of how nsITelemetry.idl and will update the page.

What is the review procedure for editing MDN? The getting started section tells me it's a publicly editable wiki, and I already have an account.

Comment 3

[Georg Fritzsche [:gfritzsche]]

Cheers!
You could just edit the page, then before finishing the edit make sure to mark the checkbox for "Review needed? Technical" at the bottom of the edit form.
Then you can flag me here and i can take a look over it.

Comment 4

[Aditya Bharti [:adbugger]]

Made changes to the "Method Overview" section and the "Constants" section. Will change the attributes and methods sections in a bit. 

Marked for technical review, but I'm unable to see any sort of "review" flag on MDN. Maybe I just don't know where to look. In any case, flagging you here and awaiting feedback.

Comment 5

[Georg Fritzsche [:gfritzsche]]

Thanks!
I'm short on time today - Alessio, could you take a look over it?
The steps are documented here:
https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Do_a_technical_review

Comment 6

[Alessio Placitelli [:Dexter]]

(In reply to Georg Fritzsche [:gfritzsche] from comment #5)
> Thanks!
> I'm short on time today - Alessio, could you take a look over it?
> The steps are documented here:
> https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/
> Do_a_technical_review

Sure, I'll do!

Comment 7

[Alessio Placitelli [:Dexter]]

(In reply to Aditya Bharti [:adbugger] from comment #4)
> Made changes to the "Method Overview" section and the "Constants" section.
> Will change the attributes and methods sections in a bit. 

Thanks! Would you kindly make a few more changes? 

- Let's remove the content from the "Example" section, starting from "The following code sample shows..."
- "canRecord" is no longer available. There's canRecordBase/canRecordExtended but they are deprecated in favour of canRecordRelease/canRecordPreRelease . We should probably mark them as deprecated (as done here: https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Reference/Interface/nsIJSON)

Things to mark as deprecated:

* canRecordBase
* canRecordExtended
* newHistogram
* setHistogramRecordingEnabled (??)

- Things to ark as test-only (not to be used outside of tests):

* clearEvents
* clearScalars

> Marked for technical review, but I'm unable to see any sort of "review" flag
> on MDN. Maybe I just don't know where to look. In any case, flagging you
> here and awaiting feedback.

You did the right thing :) Flagging that for technical review is enough.

Comment 8

[Aditya Bharti [:adbugger]]

Made the required changes. Please take a look. 

If everything looks good, I will remove the contect which has been struck through. All of that is no longer present in nsITelemetry.idl. Also, it appears that newHistogram has also been removed from the idl file. Should I leave it as deprecated or remove it entirely?

Since I did not know the version numbers, I've marked the things as deprecated but ommitted the "since version" field.

Comment 9

[Alessio Placitelli [:Dexter]]

(In reply to Aditya Bharti [:adbugger] from comment #8)
> Made the required changes. Please take a look. 
> 
> If everything looks good, I will remove the contect which has been struck
> through. All of that is no longer present in nsITelemetry.idl. Also, it
> appears that newHistogram has also been removed from the idl file. Should I
> leave it as deprecated or remove it entirely?
> 
> Since I did not know the version numbers, I've marked the things as
> deprecated but ommitted the "since version" field.

Good, I've completed the technical review and dropped the functions that were no longer there.
Thanks for taking this bug. I'll close it as fixed!