656958 - Update the documentation for APIDoc syntax in the Wiki

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P2)

Description

[Will Bamberg [:wbamberg]]

https://wiki.mozilla.org/Labs/Jetpack/SDK/Writing_Documentation#On_APIDoc_Syntax is out of date.

Comment 1

[Myk Melez [:myk] [@mykmelez]]

We'll want to do this before we start really pushing to get folks to create third-party APIs.

Comment 2

[Will Bamberg [:wbamberg]]

Attachment: Updated and expanded APIDoc syntax documentation in the Wiki

Comment 3

[Dietrich Ayala (:dietrich)]

Comment on attachment 538649 [details]
Updated and expanded APIDoc syntax documentation in the Wiki

* "All of the documentation is generated on the fly from source files located in the directory structure." - should clarify this, since it sounds like you mean from the *source code* files, which is not the case.
* should link "APIDoc syntax" to the section below, or add "(see below)" or something like that.
* "The main benefit of using a defined syntax is that we can ensure that all APIs are consistently documented. Having said that, we'd like to move to a more standard syntax in the future." - "more standard" isn't clear. Maybe give an example, or use "more widely-used API documentation syntax" instead?
* "APIDoc defines the following component types: " - you use "component" throughout, which makes things sound more complicated than they actually are. "the following types" sounds just fine methinks. Component is such an overloaded term, that I'd suggest trying to not use it wherever possible here. For example, instead of "Common Component Syntax", you could say "Basic Usage", which is way less scary/snore-y. Or maybe 'component' is just way overloaded for me...
* in the Class bit, you have a typo: "<api-name="Widget">"

r+ with these changes!

Comment 4

[Will Bamberg [:wbamberg]]

Thanks Dietrich!

> * "APIDoc defines the following component types: " - you use "component"
> throughout, which makes things sound more complicated than they actually
> are. "the following types" sounds just fine methinks. Component is such an
> overloaded term, that I'd suggest trying to not use it wherever possible
> here. For example, instead of "Common Component Syntax", you could say
> "Basic Usage", which is way less scary/snore-y. Or maybe 'component' is just
> way overloaded for me...

I had a bit of difficulty with this: I agree with you about "component", but it's hard to know how to refer to the parts of an API. I've tended change it to "element" here, but not sure if that's really much better.