Design and Implement an end-to-end Documentation system for PhantomJS

[detro]

detroniz...@gmail.com commented:

PhantomJS runtime is made of a "composed" API: C++ objects binded via QtWebKit-bridge, and JavaScript shims.

This gives us enormous flexibility, but makes the API very difficult to document.

Currently the doc is made manually at http://code.google.com/p/phantomjs/wiki/Interface. While that is a good thing, if you look deep enough you will find:

• API missing
• API mis-documented

not big deals for the "savvy ones" that are ok at jumping inside the source code and figure out what an API does. But it's terrible for a "normal" user.

So, we need a better approach. Maybe look at how NodeJS does generate their (amazing!) docs (http://nodejs.org/api/index.html).

We don't have a silver bullet yet: we need to come up with this collectively.
This is not an internal design choice: is something that requires a wide spread support from all the devs, to make sure that the final result is a) maintainable b) easy to understand c) final result looks good (we care about that, don't we?) d) generated in a semi-automatic fashion.

So, what you guys think?

Disclaimer:
This issue was migrated on 2013-03-15 from the project's former issue tracker on Google Code, Issue #627.
🌟   3 people had starred this issue at the time of migration.

[detro]

detroniz...@gmail.com commented:

Here you go: http://nodejs.org/api/documentation.html

[n1k0]

nperria...@gmail.com commented:

An exhaustive contribution guide would also be very welcome, especially for people with zero c++ background like me to get started :)

[detro]

detroniz...@gmail.com commented:

Well, that could definitely be fitted in.

But I'd say: Qt and QtWebkit Documentation is the place to start from.

[ariya]

ariya.hi...@gmail.com commented:

What about using JSDuck? https://github.com/senchalabs/jsduck

Example of the result: http://docs.sencha.com/touch/2-0/ and http://docs.appcelerator.com/titanium/2.0/index.html and many others.

Note that we don't need to extract the doc from the real code, we can just prepare "fake" JavaScript files which will be extracted and processed by JSDuck. These files won't contain code, they just has all the function definition and the accompanying annotation tags.

[detro]

detroniz...@gmail.com commented:

I didn't know about this project actually.
Looks good.

About not needing to extract the doc from the real code, it makes sense but
I'm only concerned about human error. We (me!) can forget to update the doc.

If I understand correctly, Node uses a little Node script + markdown module
to generate the doc.
Every module is ASSUMED to have a <modulename.js> and a correspective doc/<
modulename.md> that provides examples and other docs.
But I guess, even in that case, the dev has to put effort into the markdown
file to provide examples and other things like that. So, the issue is only
partially solved.

What I like about the Node doc is that it's a set of generated static files.
It's very "portable".

Sencha doc seems to be doing heavy use of Ajax: that can be made "portable"
too (poiting to ./json_files), but I don't know it's internals yet to know
what exactly does.

[davidrapin]

david.rapin@gmail.com commented:

What I like about the Node.js way, is that code and doc live next to each other, which makes it simpler for developers to document a feature they just added.
The "portable" aspect is good too.

[ariya]

ariya.hi...@gmail.com commented:

The advantage of JSDuck-generated one is the quick search with auto complete (try the search box). However, I agree that static files are great too.

[detro]

detroniz...@gmail.com commented:

While I think JSDuck is a good solution, I'll put down in here reference links for now.

JSDuck

• https://github.com/senchalabs/jsduck
• https://vimeo.com/33465319 << introduction talk about JSDuck
• https://github.com/senchalabs/jsduck/wiki/Guide << rich guide

Node

• https://github.com/joyent/node/tree/master/tools/doc << explains how the tool works
• http://nodejs.org/api/documentation.html << explains how the doc is structured
• http://nodejs.org/api/index.html << well, the actual node doc

I guess, whoever takes a stab at this first, will set the path. Unless she really gets it wrong: in that case, will make sure my nagging is heard :)

[ariya]

ariya.hi...@gmail.com commented:

 

 
Metadata Updates

• Milestone updated: Release1.7 (was: FutureRelease)

[ariya]

ariya.hi...@gmail.com commented:

I've played with both during the weekend. Here is what I found out.

JSDuck is really geared toward that kind of application using the "fake class" concept in JavaScript. I have not found an easy way to make it understand the concept of module, which we implement. Seems that the Titanium flavor has a way to define module but trying to get Titanium set up for my environment was going-down-the-rabbit-hole activity for me. An alternative would be to create a custom JSDuck and for that I was already out of my time quota.

Node generator script is just a fancy Markdown-to-HTML converter as it does not scan and parse any JavaScript files for understanding the structure and/or annotations. It's rather easy to setup but I doubt the benefit is more another dozens Markdown-based tools out there.

[detro]

detroniz...@gmail.com commented:

I guess the answer is "easy": whoever does it, decides the path (under
reasonable argumentation).

If someone says "let's write Java Interfaces of our modules and run javadoc
on it" I won't call it "reasonable argument", for example. :)

[detro]

detroniz...@gmail.com commented:

Mmm, I thought from https://github.com/senchalabs/jsduck/wiki/Guide that
JSDuck could be used in a "generic enough way".

Am I totally wrong?

[ariya]

ariya.hi...@gmail.com commented:

"generic" enough does not mean "out of the box". I found out that the Titanium version of JSDuck, which produces the doc style that I want (modules etc), is a fork with some additional functionalities. However, I didn't manage to install it.

[detro]

detroniz...@gmail.com commented:

Wait. JSDuck is from Sencha, right? You are Sencha, right?

You think JSDuck is too much tailored towards Sencha stuff?
That's the JSDuck I refer too: I didn't get the Titanium thingy...

[ariya]

ariya.hi...@gmail.com commented:

It's precisely what I have written before: JSDuck is useful to document application using the "fake class" concept in JavaScript. We don't, we use modules concept. In that case, we need to tweak it or use JSDuck's fork from Titanium.

[ariya]

ariya.hi...@gmail.com commented:

I'm not happy with pure Markdown-based solution from Node.js generator because it means we write the documentation separated from the source file. It is better if the annotation in e.g. module code will serve as the documentation content just like javadoc, qdoc, doxygen, etc.

Investigating JSDoc now. It seems attractive, e.g. http://usejsdoc.org/howto-commonjs-modules.html.

[detro]

detroniz...@gmail.com commented:

I doubt we can achieve that.
We will always have to write the documentation separate from the code.

How would we document the mix of QObject-exposed-methods with pure-JS methods?
We could end up making every exposed Qt Slot wrapped in a useless JS method: that would make us have to maintain real-code and doc-code anyway.

That's why a drastic "code on one side - doc on the other side" sounded feasible.

After all, in comment #4 (http://code.google.com/p/phantomjs/issues/detail?id=627#c4) you seemed much more keep to this approach (unless I read this comment wrong).

[ariya]

ariya.hi...@gmail.com commented:

If there is a documentation text which is not associated with the real actual code, create an annotation that will still get parsed by the doc tool although there is no code for that. That's what I essentially commented before.

Having the code in a completely separated place than the doc defeats DRY principle. It's error prone since it's bound to be out of sync pretty easily.

[ariya]

joniscoo...@googlemail.com commented:

 

 
Metadata Updates

• CC(s) removed:
  • joniscoo...@googlemail.com

[detro]

detroniz...@gmail.com commented:

I resolve to the same conclusion.

The doers decides.
Whatever solution you can come up with for the doc, I'll not question that.
:)

The important thing is that we need good documentation, because we lack it.
The easiest it will be to write it and maintain it, the better.

[detro]

detroniz...@gmail.com commented:

 

 
Metadata Updates

• Owner updated: ariya.hi...@gmail.com

[JamesMGreene]

james.m....@gmail.com commented:

Microsoft's new release of TypeScript has Ambient Declarations (see language spec), which might make for an interesting way to document the API (basically like a header file):

Examples:

• http://typescript.codeplex.com/SourceControl/changeset/view/d397c54a55db#samples%2fjquery%2fjquery.d.ts
• http://typescript.codeplex.com/SourceControl/changeset/view/d397c54a55db#samples%2fnode%2fnode.d.ts

Just throwing it out there for shared review. :)

[ariya]

ariya.hi...@gmail.com commented:

 

 
Metadata Updates

• Milestone updated: Release1.8 (was: Release1.7)

[ariya]

ariya.hi...@gmail.com commented:

Rescheduled to 1.9.

 
Metadata Updates

• Milestone updated: Release1.9 (was: Release1.8)

[JamesMGreene]

james.m....@gmail.com commented:

JSDoc now has a "commentsOnly" plugin (https://groups.google.com/d/msg/jsdoc-users/1mxZrr9kq7U/03ONaAIFaxgJ) that can be executed against any sort of code file and it will only pay attention to the JSDoc-style annotations (comments). This would allow us to run it against the C++ files, too.

[execjosh]

Daux.io might be useful? Maybe not?

[JamesMGreene]

Looks like it basically does the same thing that GitHub.com does plus some Bootstrap themes. That may still be helpful but I think the hope was to have the docs (or perhaps intermediary Markdown) generated from source comments (like JSDoc, etc.) if possible so that we don't forget to update an external doc file (i.e. like we forget to update the Wiki). The trick is to correctly merge the exposed C++ methods with the JS ones.

[execjosh]

I see. Do you know if there has been any progress on the generation toolset?

[JamesMGreene]

No progress that I've heard of. I think we would probably just need to use Doxygen + QDoc formatted comments.

[stale]

Due to our very limited maintenance capacity (see #14541 for more details), we need to prioritize our development focus on other tasks. Therefore, this issue will be automatically closed. In the future, if we see the need to attend to this issue again, then it will be reopened. Thank you for your contribution!