How to easily document a component

SWAC makes it easy to document your components.
With the concept of functional documentation you get more as a simple documentation webpage from your documentation effort.

Generated documentation pages

You get automatically generated documentation pages from your component code. There are areas showing the expected or optional used data from the datasets given to your component. And the requirements to a template code are documented, too. Furthermore there is a section showing the available templates with highlighted code. And the dependencies of your component are listed, too.
And its easy to create a documentation just do:

<div id="compDescription" swa="EXPLAIN SWAC_edit"></div>
        

Checking datasets

But if you documented the data requirements of your component your documentation is not only used for an explanation page. When a component becomes data it is allways checked against the requirements. If there is a required attribute missing in your data swac will inform you.

Checking templates

Templates are checked, too. If there is a element missing wich you decleared as required then SWAC will give you an error of this.

Data delivery optimisation hints

If the data you give to a component is not completely used by it you get hints (with activated hint mode). So you can optimise your datasource or interface to not deliver more data than needed.

Automatic including dependencies

All files you documented as dependencies are automatically included for you, when the component loads. So you don't have to add script tags on your page.

Start documenting now

The way of documenting is included in the component template. Every documentation belonges to the "desc" attribute of your component.
These are the documentation attributs within the desc-Attribute:

/**
 * Sample component for development of own components
 */

class Sample extends Component {

    /*
     * Constructs a new component object and transfers the config to the
     * object
     */
    constructor(options = {}) {
        super(options);
        this.name = 'Sample';

        this.desc.text = 'Description of this component for documentation.';
        this.desc.depends[0] = {
            name: 'dependency.js',
            path: SWAC.config.swac_root + '/swac/components/Sample/libs/dependency.js',
            desc: 'Description for what the file is required.'
        };
        this.desc.templates[0] = {
            name: 'templatefilename',
            style: 'stylefilename',
            desc: 'Description of the template.'
        };
        this.desc.styles[0] = {
            selc: 'cssSelectorForTheStyle',
            desc: 'Description of the provided style.'
        };
        this.desc.reqPerTpl[0] = {
            selc: 'cssSelectorForRequiredElement',
            desc: 'Description why the element is expected in the template'
        };
        this.desc.optPerTpl[0] = {
            selc: 'cssSelectorForOptionalElement',
            desc: 'Description what is the expected effect, when this element is in the template.'
        };
        this.desc.optPerPage[0] = {
            selc: 'cssSelectorForOptionalElement',
            desc: 'Description what the component does with the element if its there.'
        };
        this.desc.reqPerSet[0] = {
            name: 'id',
            desc: 'The attribute id is required for the component to work properly.'
        };
        this.desc.optPerSet[0] = {
            name: 'nameOfTheAttributeOptionalInEachSet',
            desc: 'Description what is the expected effect, when this attribute is in the set.'
        };
        // opts ids over 1000 are reserved for Component independend options
        this.desc.opts[0] = {
            name: "OptionsName",
            desc: "This is the description of an option"
        };
        // Setting a default value, only applying when the options parameter does not contain this option
        if (!options.OptionsName)
            this.options.OptionsName = 'defaultvalue';
        // Sample for useing the general option showWhenNoData
        if (!options.showWhenNoData)
            this.options.showWhenNoData = true;
        // function ids over 1000 are reserved for Component independend functions
        this.desc.funcs[0] = {
            name: 'name of the function',
            desc: 'Functions description',
            params: [
                {
                    name: 'name of the parameter',
                    desc: 'Description of the parameter',
                    type: 'Expected type(s) of parameter'
                }
            ],
            returns: {
                desc: 'Description of the return value',
                type: 'WatchableSet'
            }
        };

        //Documentation for events the component can fire
        this.desc.events[0] = {
            name: 'swac_REQUESTOR_ID_sample_click',
            desc: 'An event fired when the user clicks on the component.',
            data: 'Delivers the JS event object of the click event.'
        }
    }

    /*
     * This method will be called when the component is complete loaded
     * At this thime the template code is loaded, the data inserted into the 
     * template and even plugins are ready to use.
     */ 
    init() {
        return new Promise((resolve, reject) => {

            // here we can do what we want with the data and template.
            
            // we can access the date over the data attrbute
            console.log('Data inside the sample component:');
            console.log(this.data);
            
            resolve();
        });
    }
}