JavaScript API documentation

[Alfonso Martínez de Lizarrondo]

I think that we can try to use ​JSDoc to generate full documentation for the js files and that way get a better overview of the code and help the people to use better the API and get involved with the project.

I'm gonna take a look at it and do some little test to see if it can really help us. (I wanted to check if the range implementation could help me to fix a bug, but the first part is to read the file and see what methods does it provide, so having a parser that summarizes it is very helpful)

[Alfonso Martínez de Lizarrondo]

sample output after little changes

[Alfonso Martínez de Lizarrondo]

I've done some changes to the fckdomrange.js file and then used the JSDoc on it and I've attached here the outcome (as well as the modified .js file to understand better the outcome)

It's quite easy to use and it can process all the files in the _source folder, although I think that the duality of functions between the IE and the Gecko version does generate some warnings.

Without any special thing it can already generate useful output, but putting the comments the proper way and providing the type of the return values makes things even better.

To use it I only had to install ActivePerl, and then using the ppm command install the HTML-template after that the script runs without problems.

[Frederico Caldeira Knabben]

I had also made some tests previously and liked the results. The only design mistake JSDoc authors did is to really expect to have the same output as they have with JavaDoc, instead of targeting it to JavaScript features, as it has really few similarities with Java (that damned name confuses people!).

So JSDoc is quite "class oriented". Objects like FCK or FCKTools, are exceptions of it, which makes things strange for those objects.

I've worked on a project 2 years ago, and we have produced the JavaScript documentation with JSDoc. I've introduced some kind of internal rules for objects, to document them differently of classes. Maybe we could try the same thing here. Let's check if other options are not available in the market too.

In any case, this kind of documentation was planned for the 3.0. So, I'm targeting it to it.

[Alfonso Martínez de Lizarrondo]

The JSDoc project might not be itself the right tool nowadays to generate the documentation, I've seen also that now there's a ​JsDoc Toolkit project to create a new version done in Javascript and improving the capabilities (other tools are linked here ​http://code.google.com/p/jsdoc-2/wiki/OtherDocs ).

So I think that one way or another the JSDoc syntax itself for the comments is the interesting part, so we could try to put the comments that way so it can be parsed by any of these tools instead of having to read all the functions to understand how it works. It's just a matter to put the comments that way when we change some code, no need to start documenting everything at once.

I would suggest to update the CodingStyle page so it does suggest documenting the code according to these rules

[Frederico Caldeira Knabben]

The CKEditor prototype is using the ​JsDoc Toolkit for the API documentation.

To build the documentation HTML files from the source code, the "_dev/docs_build/docs_build.bat" batch file has been created. The generated docs will be placed in the "_docs/api" folder. This folder has been marked as "ignore" in the SVN, so it will not be available on checkout, and will not disturb on commit.

A customized version of the JsDoc Toolkit code is available in the "_dev/_thirdparty/jsdoc-toolkit" folder. It contains mainly changes to the templates to reflect our needs. It also contains core changes to introduce some features to it. The most relevant addition is the possibility to defined default values for documentation tags by config file. This feature was not accepted by the JsDoc Toolkit core developer, unfortunately (​see ticket).

The following things are automatically filled if not present in the code documentation:

• A red "NO DOCUMENTATION AVAILABLE" text appears for undocumented functions.

• A red "NO EXAMPLE AVAILABLE" text appears if no example is available for a member. Usually examples are required as they are the easiest way to understand things. But, in some cases, there is no need to have examples. In such cases it is enough to define an empty "@example" tag in the code.

• All member types are set to "Undefined".

• The @since tag is filled with "3.0". It means that all members in the documentation will have the "Since 3.0" mark at our first release. After that, we should start using the @since keywork on new things, to indicate that a feature has been added later.

• Just like @since, the @version tag will be filled with "3.0".

It looks like all our customizations to the JsDoc Toolkit code can be done in the templates instead. This would be much better as it will make it easier to upgrade on the JsDoc Toolkit releases.

But, the scope of this ticket is not defining the template to be used, but the system we are using for documentation. We'll have a dedicated ticket to the template.

[Frederico Caldeira Knabben]

I'm working on the template thing, to avoid touching the JsDoc Toolkit code. I'll ask review again after it.

[Frederico Caldeira Knabben]

The JsDoc Toolkit code is now an SVN external. No changes to their code are needed anymore. A custom template has been created and placed in the "_dev/docs_build/template" folder. It is a copy of the default jsdoc template, with the features described two comments above.

[Martin Kou]

1. Shouldn't the slashes used for paths in docs_build.bat be replaced with backslashes, since the .bat file is run in Windows?
2. Even with point 1 fixed, it is still not building any readable documentation in the _docs/api directory.

[Frederico Caldeira Knabben]

Replying to martinkou:

1. Shouldn't the slashes used for paths in docs_build.bat be replaced with backslashes, since the .bat file is run in Windows?

On Windows you can actually use both the slash and backslash. The later is also compatible with other platforms, so I always try to use backslash on paths.

2. Even with point 1 fixed, it is still not building any readable documentation in the _docs/api directory.

Introduced with [2343], fixed with [2344].