Documentation about Frontend, Backend, Connector, Installation & Administration.
The intent of this documentation is to give you a great over all introduction about OpenHaus.
This repo containes files where the documentaiton is generated via https://docsify.js.org. Long story short, i could find a documentation tool that matches my needs. So i searched around and put something custom together. Basicly we download the uncrompressed source code and parse the comments in it. Then a template is filled with the harvested data and for each file a markdown output is generated. The markdown file can then be used in docsify. et voilà: Autogenerated documentaiton from source code.
If you want to improve the docs, you have do modifie the source code of the following parts:
The only execption are the "Administration" section.
Please follow the order of tags and how they are used.
See How to document the source code below.
Any contribuation is welcomed. Dont know where to start? Open a issue and start asking. This is not limited to the documention, klick on the Organization and start looking arround.
Any help is appreciated. Dosnt matter how small or big.
There are 2 main block of comments. class & functions.
/**
* @class foo
*//**
* @function bar
*/This code can be anywhere in the file you want to document.
To add a description to a class, use @description tag:
/**
* @description
* Descriopt goes here
*
* @class callsName
*/For a function you can write the description directly under the @function tag:
/**
* @function fnc
* Description goes here
*/To document parameter & propertys, use the @param and @property tags.
/**
* @description
* This is to demonstrate the documentation<br />
* You can use multiple line breaks or even <br />
* [markdown](example.com) in it.
*
* @class myClass
* @extends Array https://example.com
*
*/
class myClass{
constructor(prop1, prop2){
this.prop1 = prop1;
this.prop2 = prop2;
this.timestamp = Date.now();
}
/**
* @function method
* This function returns the passed object
*
* @param {Object} param1 Any object type you want
*
* @returns {Object} input object
*/
method(param1){
return {...param1};
}
}Above you can see how to document a class with methods.
As well you can see that we extend the Array super class.
The @extends tag support links to other documentation: Either a full link, or a internal link, e.g: system/component/class.base.js
| Tag | Description |
|---|---|
@class |
Declares the comment block as a class description |
@property |
Defines a class property |
@param |
Defines a constructor/function parameter |
@function |
Declares the comment block as function/method description |
@extends |
Indicates that a class extends some other class |
@see |
Internal link to some other file/documentation |
@link |
External link to something |
@returns |
Describe what a function returns |
@emits |
Events are documented |
@example |
Document example code |
For a better understanding, take a look on the jsdoc specification: https://jsdoc.app
/**
* @description
* The description goes first!
* For classes only, if you define a function,
* use the @function tag instead and skip the description tag
*
* @class name After the description tag, comes the class tag
* @extends Array optional extends tag, directly after the class tag
*
* @param {Object} obj Then parameter are document
*
* @property {Array} items Then propertys
*
* @emits What ever is emitted
*
* @example
* ```js
* ...
* ```
*
* @returns {String} If you document a function, this is the place where the return tag is used
*
* @see As last items
* @link are links documented
*/- Description/Function
- Class
- Extends
- Parameter
- Propertys
- Events
- Examples
- Return Value
- Additional links
This order helps to keep a consistent documentation of the source code.