630415 - Shared Modules Refactor -- Find out how Jetpack is autogenerating docs

Status: RESOLVED FIXED

(Mozilla QA Graveyard :: Mozmill Tests, defect)

Description

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

Analyze Jetpack/ask devs to see how docgen is working. If possible, we want to adopt the same solution and align on their documentation format.

Comment 1

[Henrik Skupin [:whimboo][⌚️UTC+2] (away 02/17 - 02/21)]

Not sure, if we really need this amount of bugs for doing documentation work. It would have been enough to have one single bug which covers it for all included elements in sprint 1. Not everything has to be part of bugzilla. Also we should use a whiteboard entry to simply query for shared module refactoring bugs.

Comment 2

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

I want broken down tasks, and I think this level of granularity is appropriate. It is possible tracking them in bugzilla won't be the most effective way to do this. Let's talk more offline.

Comment 3

[Geo Mealer [:geo] -- This account is inactive after 2015-07-07]

Jetpack is generating docs using markdown with a bunch of extensions. Contrary to my initial take, it's not docgen'ing from the JS files, but rather using a bunch of .md files crafted on the side.

Internal to the .js files, they're still using basic javadoc format for consistency with the rest of Mozilla, but there's no expectation of docgen. It's just a commenting style.

We could still consider going for something like markdown; there'd be a benefit in that docs would be checked in with the code. However, I'm not seeing any viable docgen solution at all, and think we should probably abandon that approach for the time being.