Skip to content

How the documentation is generated

Jump to bottom
DigitalBox98 edited this page May 21, 2024 · 21 revisions

Initial creation

The original/commented files are inside the docs/synoextjsdocs-source.tar.gz file. JSduck is required to generate the documentation

Install jsduck 2.7.6:
an old version of ruby is required, please follow the instructions on https://gist.github.com/defaye/47aa2ca29b17e8ec6315c0bc3118abcf then install jsduck

sudo $HOME/.rbenv/versions/2.7.6/bin/gem install jsduck -- --with-cflags="-Wno-error=implicit-int -Wno-error=implicit-function-declaration"

Check install :

$HOME/.rbenv/versions/2.7.6/bin/jsduck --version

To generate the documentation, the steps are quite simple :

tar -xvf synoextjsdocs-source.tar.gz 
cd SynoExtJSDocs
jsduck syno/ --output docs --welcome=welcome_page.html --guides=guides.json

The documentation is now available in the "docs" folder via the index.html page

Documentation structure

  • synoextjsdocs-source.tar.gz : archive with folder "SynoExtJSDocs" containing the source of the documentation with an empty "docs" folder
  • synoextjsdocs.tar.gz : archive with folder "docs" only containing the documentation generated

How the documentation is enriched

The steps to enrich the API documentation is as below :

  • If possible, before enriching the documentation, the SimpleExtJSApp application will be updated to contain the additional GUI component
  • Add comments for the desired DSM component in the corresponding source file in the "syno" directory
  • Identify if this component extends from ExtJS 3.4 component
  • If so, copy the corresponding ExtJS 3.4 source file from the "ext-3.4.1/src/" directory to the "syno/scripts/ext-3.4/src/" directory by applying the same directory structure
  • Follow the next steps described in "how the documentation is generated"

That's it !

Examples

Below are examples of comments added which will be used during the documentation generation :

From syno/scripts/ext-3.4/ux/ux-all.js :

/**
 * @class SYNO.ux.Button
 * @extends Ext.Button
 * Simple Button class
 * @xtype syno_button
 *
 */

From syno/scripts/ext-3.4/src/data/Store.js :

/**
 * @class Ext.data.Store
 * @extends Ext.util.Observable
 * <p>The Store class encapsulates a client side cache of {@link Ext.data.Record Record}
 * objects which provide input data for Components such as the {@link Ext.grid.GridPanel GridPanel},
 * the {@link Ext.form.ComboBox ComboBox}, or the {@link Ext.DataView DataView}.</p>
 * <p><u>Retrieving Data</u></p>
 * <p>A Store object may access a data object using:<div class="mdetail-params"><ul>
 * <li>{@link #proxy configured implementation} of {@link Ext.data.DataProxy DataProxy}</li>
 * <li>{@link #data} to automatically pass in data</li>
 * <li>{@link #loadData} to manually pass in data</li>
 * </ul></div></p>
 * <p><u>Reading Data</u></p>
 * <p>A Store object has no inherent knowledge of the format of the data object (it could be
 * an Array, XML, or JSON). A Store object uses an appropriate {@link #reader configured implementation}
 * of a {@link Ext.data.DataReader DataReader} to create {@link Ext.data.Record Record} instances from the data
 * object.</p>
 * <p><u>Store Types</u></p>
 * <p>There are several implementations of Store available which are customized for use with
 * a specific DataReader implementation.  Here is an example using an ArrayStore which implicitly
 * creates a reader commensurate to an Array data object.</p>
 * <pre><code>
var myStore = new Ext.data.ArrayStore({
    fields: ['fullname', 'first'],
    idIndex: 0 // id for each record will be the first element
});
 * </code></pre>
 * <p>For custom implementations create a basic {@link Ext.data.Store} configured as needed:</p>
 * <pre><code>
*/

Documentation generated :

image

Clone this wiki locally