791974 - Create script to generate documentation based on jsdoc comments

Status: RESOLVED WONTFIX

(Mozilla QA Graveyard :: Mozmill Tests, defect)

Description

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Right now we have a poor documentation or well nothing for our shared modules. I consider this as bad because it makes it increasingly hard for new members to get in touch with the code. We should continue our efforts in documenting the methods of all the modules by using the jsdoc style.

What we want to use is: http://code.google.com/p/jsdoc-toolkit/

A file which already contains documentation for everything is the assertions module:

http://hg.mozilla.org/qa/mozmill-tests/file/default/lib/assertions.js

All the other files under the following folder should be updated in a similar way:

http://hg.mozilla.org/qa/mozmill-tests/file/default/lib/assertions.js

To create the documentation with jsdoc-toolkit you will have to grab the latest version and run the following command:

bash jsrun.sh -r -t=templates/outline/ --exclude="test_*" ../mozmill-tests/lib/

An example how it can look like you can find here:

http://people.mozilla.com/~hskupin/docs/mozmill-tests/outline/symbols/Expect.html

To get this right I would propose that we upload patches for each individual module. It will make it easier to review.

Comment 1

[Johannes Vogel (:nebelhom)]

Hi :whimboo ,

I found this bug and it looked more inline with my limited skills, so I tried my hand at it. I have a couple of comments before I submit a patch. I asked Dave if it is still current.

1) the template "outline" does not exist in the currently available version of jsdoc (2.4.0) only a template called "jsdoc", where the result looks fairly different to what you propose in

http://people.mozilla.com/~hskupin/docs/mozmill-tests/outline/symbols/Expect.html

2) --exclude="test_*" for some reason excludes every single file giving an empty documentation. So I ran it without this statement. Is this an issue?

I attached the CLI output given for the two trials that I ran with this program, for you to have a look at

3) If everything is ok, how should I submit the documentation? As a patch with a new folder in mozmill-tests (if so in which sub-directory)?

4) In an attempt to circumvent the above difficulties, I tried my hand at using jsdoc3 (the latest version) which can be found here:

https://github.com/jsdoc3/jsdoc

Unfortunately, I couldn't even get the documentation to be created due to various syntax errors that are apparently in the code or something like that. I attached the output to this one, as well, just in case someone is interested, but I will ignore that version for the moment, unless you want me to get it to work.

Anyhow, that's it, sorry for the long post.

Johannes

Comment 2

[Johannes Vogel (:nebelhom)]

Attachment: CLI Output for jsdoc2.4.0

Comment 3

[Johannes Vogel (:nebelhom)]

Attachment: CLI Output for jsdoc3

Comment 4

[Henrik Skupin [:whimboo][⌚️UTC+1]]

(In reply to Johannes Vogel (:nebelhom) from comment #1)
> I found this bug and it looked more inline with my limited skills, so I
> tried my hand at it. I have a couple of comments before I submit a patch. I
> asked Dave if it is still current.
> 
> 1) the template "outline" does not exist in the currently available version
> of jsdoc (2.4.0) only a template called "jsdoc", where the result looks
> fairly different to what you propose in
> 
> http://people.mozilla.com/~hskupin/docs/mozmill-tests/outline/symbols/Expect.
> html

It should be that one:
http://jproton.googlecode.com/files/outline.template-0.1.zip

But so far we haven't decided to use any of the templates yet, given that all of them have limitations and we would have to create a customized version for our needs. We haven't had the time for that task yet, also given that we don't know the full specs for such a template yet. Once we have the jsdocs in all of our files we might know better. So thanks for your interest on this bug!

> 2) --exclude="test_*" for some reason excludes every single file giving an
> empty documentation. So I ran it without this statement. Is this an issue?

You should run it only for the lib modules and nothing else. I haven't used the tool for a long time and don't know what --exclude is exactly doing. 

> 3) If everything is ok, how should I submit the documentation? As a patch
> with a new folder in mozmill-tests (if so in which sub-directory)?

The documentation will not be part of the repository. We will have to find a place where to host it. mozqa.com might be a good idea. The task on this part is to create the jsdoc comments only.

> 4) In an attempt to circumvent the above difficulties, I tried my hand at
> using jsdoc3 (the latest version) which can be found here:
> 
> https://github.com/jsdoc3/jsdoc
>
> Unfortunately, I couldn't even get the documentation to be created due to
> various syntax errors that are apparently in the code or something like
> that. I attached the output to this one, as well, just in case someone is
> interested, but I will ignore that version for the moment, unless you want
> me to get it to work.

I'm sure you want jsdoc-toolkit which is a different tool. AFAIR we had a lot of trouble in the past with jsdoc given that it uses an really outdated version of the Rhino engine. Not sure if something has been changed meanwhile, but the problems you report here might be highly correlated.

Comment 5

[Henrik Skupin [:whimboo][⌚️UTC+1]]

Not needed anymore given that mozmill-tests are no longer in use.