API documentation

[pablofiumara]

Start of pdf.js documentation. Generated with JSDoc.

[yurydelendik]

Crosspost at https://groups.google.com/forum/#!topic/mozilla.dev.pdf-js/2EH6HQG_FVY

Can you move all resources to the ./external/jsdoc/ folder? And as discussed in the mailing list, add a build step to create output the results in the ./build/jsdoc/. We have plans to integrate that to the buildweb step to automatically generate/publish gh-pages.

[pablofiumara]

Thanks for your answer, Yury.

I have just moved the prototype of the API docs from ./out to ./external/jsdoc (I also added a line to .gitignore so that Netbeans folder is ignored by Git). Then, I commited and made a second pull request. Please, check that everything is okay.

Could you give me some guidelines on how to add a build step to the buildweb step to automatically generate/publish gh-pages, please?

I am using JSDoc. Here you will find more information about it: https://github.com/jsdoc3/jsdoc
Do you remember what kind of information was missing when you used JSDoc? How long ago did you use it? It seems it have been improved in the last months.

My idea is to design the API little by little. It won't be easy, it won't take little time but I feel I can achieve that. I just wish to contribute to the project.

Thanks in advance.

[brendandahl]

We already auto publish to gh-pages. You should add another build step to make.js (e.g target.api) and then copy that output during the target.web https://github.com/mozilla/pdf.js/blob/master/make.js#L145 step. For an example, see our new gh-pages PR #4585.

[pablofiumara]

It seems that's what I needed: a step-by-step tutorial on how to add another build step. Thanks for your answer, Brendan.

[yurydelendik]

@pablofiu, I used it couple of months ago. Yes, the https://github.com/jsdoc3/jsdoc was the best choice so far. From top of my head, there was a small defect at RenderTask, it did not add the promise field to the documentation.

[pablofiumara]

@yurydelendik : It seems JSDoc is best option but it is far from perfect. For example, it does not distinguish between functions and methods: http://usejsdoc.org/tags-method.html

I have already started to analyze code in order to build the API docs.

[pablofiumara]

Based on your comments on file ./src/display/api.js, I created API docs using JSDoc. This is a Node module installed at ./node_module/jsdoc For more information, visit http://usejsdoc.org/

API docs files are located at ./external/jsdoc as Yuri asked me. #4571 (comment)

Unfortunately, I am confused on how to add a build step as Brendan asked here: #4571 (comment) I do not understand step five: #4585 (comment)

Feel free to give me some feedback. I have just asked a merge to master.

[yurydelendik]

API docs files are located at ./external/jsdoc as Yuri asked me. #4571 (comment)

I did not ask that. I just said " move all resources to the ./external/jsdoc/ folder". If you don't have resources, e.g. style, images, additional build scripts, then you don't have to have this folder. Sorry for the confusion.

We are not interested in final output of the jsdoc. We are interested in automation of building of this output. Please remove final output from the ./external/jsdoc/. It shall be generated by make.js at the ./build/jsdoc folder.

[pablofiumara]

Please remove final output from the ./external/jsdoc/.

Done and pushed.

It shall be generated by make.js at the ./build/jsdoc folder.

This is the part which I am struggling with.

[timvandermeij]

@pablofiu Could you squash the commits into one to make review easier? See https://github.com/mozilla/pdf.js/wiki/Squashing-Commits on how to do this easily.

Regarding your make.js question: for us it's easy to be able to run one command, say node make api-docs, which generates the API documentation. Take a look at https://github.com/mozilla/pdf.js/blob/master/make.js#L1307-L1324 for an example on how to add such a command to make.js. For your purpose, just copy that command and adjust it to run the commands required for generating the documentation (jsdoc for example, but maybe more, I have not looked into this much).

Is it a bit more clear? If not, feel free to ask :)

[yurydelendik]

non related changes

[pablofiumara]

You are right. My mistake. I am sorry.

[pablofiumara]

@timvandermeij: Thanks for your detailed answer :)

It seems I have commited some changes that I should not have commited. I decided to delete my documentation branch and created a new branch named 'APIDocs' (instead of squashing the commits into one).

Tim, should I modify ./external/shelljs/shell.js in order to create a command for JSDoc? I see it has been done, for example, for cd and pwd commands.

[Snuffleupagus]

For reference, see #4616 which implements the necessary command in make.js.

[pablofiumara]

Thanks, Jonas.

Isn't
yurydelendik@2ca2c38#diff-da55c948ab565ebe30a2027fe5b721abR139
all that is needed to generate JSDoc output the corresponding Github pages?

Fiumara, Pablo Alejandro

On 13 April 2014 19:28, Jonas Jenwald [email protected] wrote:

For reference, see #4616 https://github.com/mozilla/pdf.js/pull/4616which implements the necessary command in make.js.

Reply to this email directly or view it on GitHubhttps://github.com//pull/4571#issuecomment-40322094
.

[yurydelendik]

Yury, please, remember that this was a preview. This was not a "final version" of how API docs comments. I have just commited this so that some of you agreed on making the API Docs.

Oh, I misunderstood your intent. We started contributing JSDoc comments long ago on API functions (see src/display/api.js), that has a higher priority than some classes that users are not going to deal with. And yes, you could submit documentation comments and we expect production quality comments at this time.

[pablofiumara]

No problem. I should have mentioned that I was checking if there was interest in
making API docs (indeed there was).

Yury, could you have a look at this function related to JSDoc output,
please? #4571 (comment)

Is JSDoc output being put to bin folder?
yurydelendik@2ca2c38#diff-da55c948ab565ebe30a2027fe5b721abR155

Isn't
yurydelendik@2ca2c38#diff-da55c948ab565ebe30a2027fe5b721abR139all
that is needed to generate JSDoc output the corresponding Github
pages?

Fiumara, Pablo Alejandro

On 14 April 2014 16:58, Yury Delendik [email protected] wrote:

Yury, please, remember that this was a preview. This was not a "final
version" of how API docs comments. I have just commited this so that some
of you agreed on making the API Docs.

Oh, I misunderstood your intent. We started contributing JSDoc comments
long ago on API functions (see src/display/api.js), that has a higher
priority than some classes that users are not going to deal with. And yes,
you could submit documentation comments and we expect production quality
comments at this time.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/4571#issuecomment-40410702
.

[yurydelendik]

To build the documentation, run node make jsdoc. The result will be placed at './build/jsdoc/' location.

Every time the pull request is merged, the docs are updated automatically at http://mozilla.github.io/pdf.js/api/draft/index.html

[pablofiumara]

Here's the function I wrote to generate API Docs: #4623