494970 - Document Mozilla External String Guide

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: General, defect)

Description

[David Humphrey (:humph)]

The Mozilla Internal String Guide (see https://developer.mozilla.org/En/Mozilla_internal_string_guide) is a useful and well written document.  In the first paragraph of this document it says, 

"Extensions, XULRunner applications, and embedders should use the external strings, documented here."

This takes you to an empty page.  We really need a document that is as good for developers not linking to the internal API.

Comment 1

[David Humphrey (:humph)]

Assigning as per conversation on irc.  CC'ing sheppy and bsmedberg as an fyi and for any comments/suggestions.

Comment 2

[Benjamin Smedberg]

We can probably auto-generate the same style of docs as the _internal stuff using the same static analysis tool. It probably ought to be at nsAString_external or something like that, and have nsAString be a landing page which explains the external/internal difference and directs you to one or the other (and perhaps lists some of the stupid subtle differences between then).

Comment 3

[Roger Dicke]

A workable External string guide is now up. (The URL on this bug points somewhere now!) The static analysis docs are linked in too.

Comment 4

[Eric Shepherd [:sheppy]]

These docs need reformatting pretty desperately in order to match our preferred format for API reference documentation. Also, much of the stuff has no actual documentation, just lists of functions and their parameters, with no actual discussion. However, it's a start. I've gone through and tagged the articles "NeedsContent" and "NeedsEditorialReview" for starters.

Comment 5

[Benjamin Smedberg]

Frankly, the list of methods and parameters is the most important part.

Comment 6

[Eric Shepherd [:sheppy]]

Raw lists with no explanation annoy me though. Yes, it's helpful, but without having details, it's not really documentation per se.

Comment 7

[Roger Dicke]

I'm wondering where I might find examples of what the preferred
format for API reference documentation is? I have been looking for a reference, but perhaps I don't know what I am looking for. I remember being referred to https://developer.mozilla.org/Project:en/Writing_interface_reference_documentation but I found that much of this document didn't apply to this bug. Much appreciated.

Comment 8

[Eric Shepherd [:sheppy]]

The sample interface reference should usually be pretty easily adapted to any kind of API reference documentation. What sorts of specific issues do you have? We can sort them out and come up with a plan.

https://developer.mozilla.org/Project:en/Sample_interface_document

Comment 9

[Roger Dicke]

Well, the interface documentation is great for one interface, and surly abstract and concrete classes can even be documented in a similar way. However I am working with the contents of xpcom/glue/nsStringAPI.* which includes a number of classes. Should I completely document each class? On the same page? Looking at https://developer.mozilla.org/En/Mozilla_internal_string_guide the abstract classes have "common" methods listed, and then complete listings in appendix B. When it comes to concrete classes it lists only the common classes, not even methods. Then the rest is things one might commonly want to know when working with strings. I defiantly plan to document a list of all the classes and their purpose, and now that I look at the Internal String Guide again, specifics on the abstract classes. So, what I am wondering is how much I should take form interface documentation and how much from the Internal String Guide? The great difference between the two is what makes me confused as to which I should mimic more, and what to mimic from each? Or am I just way off?

Comment 10

[Eric Shepherd [:sheppy]]

I would generally prefer using something closer to the much newer interface reference format, which I'd like to migrate our older documentation toward using as time allows.

Comment 11

[Roger Dicke]

Up until recently I was a little confused as to which documentation we were talking about, the External String Guide or the static-analysis docs. Upon realizing we were talking about the static-analysis docs I also realized the magnitude of the work to be done on it. Considering the time constraints I have, it is highly likely I will not be able to see full documentation of these pages to the end. (I have until the end of April) However I would still like to do as much work as I can on it. Are there any specific classes I should concentrate on first? Any specific parts? Or should I just do each class top to bottom? -Best Regards

Comment 12

[Benjamin Smedberg]

The static analysis pages are machine-generated and should stay that way. It's probably not worth arguing whether they are "documentation" or "reference". If somebody wants to create parallel docs which are more descriptive, that's fine, but let's focus on making the machine-generated docs as useful as possible.

The primary questions people need to know are:
* what is this class for?
* what methods does it have?
* what's the call signature of those methods

For the derived classes we want the complete API of the derived+base class, without having to wander about on several pages.

Comment 13

[Roger Dicke]

Point taken. And personally, since I am recreating these pages time and time again (as mentioned, by machine) while fixing a bug, not having to move all the hand written content over every time is preferable.
In which case (I don't edit the machine generated pages) is it then imperative that I create parallel docs which are more descriptive?

Comment 14

[Benjamin Smedberg]

No. We may end up hosting these documents on DXR, instead of on developer.mozilla.org, but for now let's just focus on getting the best auto-generated docs where we can.

Comment 15

[Eric Shepherd [:sheppy]]

Curious what came of this work. Things just... stopped.

Comment 16

[Benjamin Smedberg]

External strings are no more.