#519: JavaScript API documentation
------------------------+---------------------------------------------------
Reporter: alfonsoml | Owner:
Type: Task | Status: new
Priority: Normal | Milestone: CKEditor 3.0
Component: General | Version:
Resolution: | Keywords: Confirmed V3ProtoStruct Review?
------------------------+---------------------------------------------------
Changes (by fredck):
* keywords: Confirmed V3ProtoStruct => Confirmed V3ProtoStruct Review?
Comment:
The CKEditor prototype is using the [http://jsdoctoolkit.org/ 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
([http://code.google.com/p/jsdoc-toolkit/issues/detail?id=155 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.
--
Ticket URL: <http://dev.fckeditor.net/ticket/519#comment:5>
FCKeditor <http://www.fckeditor.net/>
The text editor for Internet
-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/
_______________________________________________
FCKeditor-Trac mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/fckeditor-trac
