834389 - cfx docs; sdocs should error if any modules or exported items are undocumented

Status: RESOLVED WONTFIX

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

Description

[Gregg Lind (Fx Strategy and Insights - Shield - Heartbeat )]

Goal:  prove* that all exported things in sdk modules have documentation.

in `python-lib/cuddlefish/docs/apiparser.py`:

1. for each js file in walk(lib/sdk):
2.   regex that file for exports.<thing>; exports[('" )?thing('" )?] and such.
3.     walk the md file for <api> tags.  complain about any mismatches, bidirectional.

If you want a more jsdoc / api looking example (that links to source, which is awesome!), consider:  http://gregglind.github.com/micropilot/

Comment 1

[Gregg Lind (Fx Strategy and Insights - Shield - Heartbeat )]

https://github.com/mozilla/addon-sdk/pull/777  WIP on unddoc'd modules.

(warning: ranting, may or may not align with Jetpack goals!)

My rubric / philosophy here:

1.  If it's exposed as an export, a decision should be made about whether to doc it.
2.  Code patches aren't complete without docs

Eventual long term excitement:

1.  Would be nice if all examples ran (at least for syntax and require-paths verification) during doc construction
2.  Having the docs with in version control with the code (and part of releases) is so awesome!  


*Suggestions*

1. In modules, augment "metadata" to add "internal":true or "document":false.  
2. In `modules-source`, maybe have '<api name='x' code=false>' for bits that don't really have code associated with them.
3. In `modules-source`, have <setup> tags, that would allow running examples more easily?
4. Make this check one of the first js/volo style jobs?

Comment 2

[Will Bamberg [:wbamberg]]

WONTFIX as the docs are now in MDN: https://developer.mozilla.org/en-US/Add-ons/SDK.