Docs JSON Format Documentation

File Structure

The generator has a specific file structure you have to use to be able to generate the docs. Each of them starts with the scope name (ie. app or gfx) which is later used to identify the docs to generate.

conf.json: general generation info (languages and scopes)
docs-base: the html/css/js source basis for every language
<lang>/: encapsulate sources for a specific language
<lang>/<ver>/<scope>: encapsulate sources for a specific version
<lang>/<ver>/<scope>: the generation sources for a specific scope

files/
├─ conf.json    # general generation info (languages and scopes)
├─ docs-base/   # the html/css/js source basis for every language
└─ <lang>/      # encapsulate sources for a specific language
   └─ <ver>/      # encapsulate sources for a specific version
      └─ <scope>/   # the generation sources for a specific scope

Each scope in the <lang>/<ver>/<scope> directory can have following source files:

files/<lang>/<ver>/<scope>/
├─ obj.json    # method definitions
├─ base.json   # template definitions
├─ navs.json   # scope categories for navigation
├─ desc/<member>.md      # large description files
└─ samples<member>.txt   # large code examples

Note: in fact, no file is reqired all the times. Following rules apply:

If obj.json is defined, it can make use of desc/<member>.md and base.json
If obj.json is not defined, the description files in the desc/ directory will be used as scope contents
If navs.json is not defined, the scope members (from obj.json or desc/) will be listed as flat index (similar to the 'All' category)

Source Files

obj.json: The main generation source in JSON Format
base.json: Template definitions for often needed members or parameters. The keys are usually the method name - but it can be any unique identifier. They are used in obj.json prefixed with an '#' to reference base.json and avoid duplicated definitions. (See Note 2)
navs.json: A structure representing navigators to make it easy for users to quickly find a certain method of the scope. There will always be a 'All' category added which includes all scope members.
You can use one level of categorization using "catname": ["subcat"] or "catname":"url" pairs:
```
 {
 	"category1": {
 		"subcategory1": ["member1", "member2" /* ... */ ],
 		"subcategory2": "<customUrl>"
 	 	/* ... */
 	},
 	"category2": ["member1", "member2" /* ... */ ]
     "category3": "customfile.htm"
 	/* ... */
 }
```
desc/<member>.md: Put large descriptions of scope members here

samples/<member>.txt: A file which includes large example codes

// an unnamed sample
<sample>
/* Your sample code> */
</sample>

// a named sample
<sample Name>
/* Your sample code> */
</sample>

JSON Format

Each member in the obj.json file can have following properties:

{
	"<membername>" : {           // the name used for sorting and filtering
	    "desc": "<description>", /* or "#<membername>.md" */
	    "isval": true,  		 // indicates that member is not a function
	    "name": "<membername>",  // displayed member name
	    "pNames": ["<name1>", "<name2>" /* ... */ ], // parameter names
	    "pTypes": ["<type1>", "<type2>" /* ... */ ], // parameter types
	    "retval": "<type>",      // the type of the return value
	    "shortDesc": "<description>", // short description for info.json
	    "subfuncs": {            // submembers of the member
	        "<memName1>": {      /* a member object */ },
	        "<memName2>": "#id"  /* id from base.json */
	    }
	}
	"params": "#id",             // copy params from base.json, in place of pNames and pTypes
}

Note 1: some values are not required under certain conditions:

name unless a custom name is used
desc and shortDesc when there is no description needed (generated from name)
retval if void / there is none
pNames and pTypes if empty or params is specified
params if pNames and pTypes are defined
subfuncs if there are none
isval if it is false

This leads to callback functions with no arguments to be representable solely by an empty object {}

Note 2: You can override member names that are copied from obj.json by appending an exclamation mark ! to the obj.json member name: "customMemName!": "#id"

JSON Examples

Basic value

from gfx/obj.json

{
    "aspect": {
		"desc": "The aspect ratio of the gfx container (display)",
		"isval": true,
		"retval": "num",
		"shortDesc": "The display aspect ratio"
	}
}

Basic method in base.json using a parameter reference

SetTween from gfx/base.json

{
    "SetTween": {
        "desc": "Sets up tween methods and properties without playing it.",
        "params": "#Tween",
        "shortDesc": "Setup tween methods"
    }
}

Basic Control using external markdown, base subf refs, callbacks and more

from gfx/app.json

{
    "CreateButton": {
		"abbrev": "btn",
		"desc": "#CreateButton.md",
		"pNames": ["text", "width", "height", "options"],
		"pTypes": ["str", "num_frc", "num_frc", "str_com-FontAwesome,Html,Monospace,Normal|Aluminium|Gray|Lego,SingleLine,Custom,AutoShrink:Auto-shrinks text to fit,AutoSize:Auto-sizes text to fit,NoPad,FillX/Y,NoSound"],
		"retval": "dso-Button",
		"shortDesc": "Creates a button control",
		"subf": {
			"AdjustColor": "#AdjustColor",
			"Animate": "#Animate",
            /* ... */
			"GetType": {
				"desc": "Returns the control class name.",
				"retval": "str-Button",
				"shortDesc": "Returns the control class name"
			},
            /* ... */
			"SetOnLongTouch": {
				"desc": "Define a callback function which is called when the button has been long pressed.",
				"pNames": ["callback"],
				"pTypes": [{}],
				"shortDesc": "Called when the button was long pressed"
			},
            /* ... */
			"Show": "#Show",
			"Tween": "#Tween"
		}
	}
}

Types

Types are represented by a 3 digit identifier. The following base types are available:

ukn: unknown
all: all types
bin: boolean
num: number
str: string
lst: list
obj: object
fnc: function
dso: app object
gvo: GameView object

Optionally you can specify a subtype of your type separated with an underscore. These are predefined values in the conf.json script. Currently only 'Number' and 'String' have subtypes available. Examples are

num_int: integer
num_mls: milliseconds
str_col: "<color>" or "#[aa]rrggbb"
str_pth: file path

If the subtype you need isn't specified here you can add custom pair any time. Example:

"num_tlx":"top left x coordinate"

if there is a fixed set of argument vales available you can append them with a '-' prefix. Separate options with pipes '|' when they are mutually exclusive or commas ',' if they are compatible. Example from Layouts:

str_com-Linear|Absolute|Frame|Card

To describe a possible argument value further you can add a description text separated with ':'. Example:

str_com-Linear:linear ordered objects|Frame|Absolute

Type Popups

If you want to use popups in a description text or in return values you can add the type separated with a ':', specifically name:type. Example:

"retval": "lst-[ values:num_int ]"
"retval": "obj-{ width:num_orw, height:num_orh }"

Cross-Doc References

You can easily referenciate other docs using the @docname format. This is widely used for 'See Also: 's

See Also: @WriteFile You can even point to parent- or subdirectories:
@../app/SaveText And add html anchors:
@../app/CreateImage#Hide
You cannot use spaces in paths but html anchors allow underscores as placeholder

Description Format

If a description exceeds a basic explanation sentence its best (but not required) to put it in a separate markdown file that is easier to edit.

The description supports basic markdown features as well as standard html tags for basic formatting:

**bold**
_italic_
*italic*
__underlined__
~~~~strikethrouh~~~~
`code line`
```code block```
[linktext](url)
[linktext]{onclick js code}
### header

Besides those there are more custom formats available that allow to write a good looking, full-featured documentation.

Types

Inside descriptions you can use types and type popups as well. The type format is the same described in the JSON section. You can use one of the following formats:

name:type
name:"type"        # "quotes" uses jQuery popups and app popups as needed
name:"type-values"
name:'type'        # 'ticks' forces app popups
name:'type-values'
"name":"desc"      # for non-alphanumerical names

Samples

A good documentation should provide examples of the described method. They can be copied and executed directly from the docs.
Each sample should have a highlighted area which shows the snipped where the method was used. Use the <b> tag for that.
You can define samples by using the tag, either in the description itself or in a member.txt file in the samples/ folder, where each scope member has its own <member>.txt file.
Use following format for each sample:

<sample MyExample>
function OnStart()
{
    <b>app.Alert( "Hello World" );</b>
}
</sample>

You can disable an example using standard html comments like

<!--sample MyExample>
    // ...
</sample-->

Inline Code Areas

If you have a short command or code example you want to include without making it a Sample block, you can use the standard <smp> HTML tag or one of the custom language specific tags: <js> <java> or <bash>. Example:

<js>img.DrawLine( 0, 0, 1, 1 );</js> Additionally you can add some attributes to change their appearance. Ie:
<js noinl> will make the code full-width instead of inline
<js nobox> will remove the grey box around the code

Custom Constructor positions

By Default the constructor line of a DroidScript object will be inserted after the first sentence (marked with a dor '.'). But you can customize that position with the %c flag:

This is a description. Followed by more description. %c

Custom Sample positions

If you want to put a sample of a sample.txt file to a specified position in your description, you can use the tag, where sample is followed by the sample name. Example:

<sample Sample Name>

Generating

in a terminal navigate to 'files' by executing $ cd files
execute $ ./generate.js to generate all docs of every language (./generate.js and node generate.js are synonym)
execute $ ./generate.js -c to foce a clean regeneration
execute $ ./generate.js -help to see more cli help
execute $ ./generate.js <lang> [..] to generate docs of a specific language
execute $ ./generate.js <scope> [..] to generate a specific scope
execute $ ./generate.js <scope>.<pattern> [..] to generate only certain members of a scope (pattern is a contained regex. - ie. app.Create will generate all members containing 'Create')
execute $ ./generate.js <lang>.<scope> [..] to generate a specific scope of a language

Note: the script will only generate a scope if any file of the scope gen folder has been modified since the last generation of this scope. disable this behaviour with the -clean option.

Full generate.js option list

[OPTIONS] [PATTERN ...]
OPTIONS:
	-l  --lang=<LANG-CODE>  2 digit code, ie. en de fr pt es ..
                            defaults to 'en'
	-al --addlang=<LANG-CODE>=<LANG-NAME>
                            adds a language to conf.json
	-as --addscope=<SCOPE-ABBREV>=<SCOPE-NAME>
                            adds a scope to conf.json
	-c  --clear             regenerate the docs completely
	-u  --update            update the docs version number
	-f  --force             force generation of otherwise skipped
	-C  --clean             delete temp files (out/ files/json/*/)
	-n  --nogen             don't generate
	-s  --server            start webserver after generating
	-v  --verbose           print more debug logs
	-h  --help              this help

PATTERN:
	generates a scope in each defined language:
	<SCOPE>[.<MEMBER-PATTERN>]
	with specified language:
	<LANG-CODE>[.<SCOPE>[.<MEMBER-PATTERN>]]

MEMBER-PATTERN:             RegEx pattern

Update Github Pages

To publish the generated html files on GitHub Pages execute the updatePages script

npm run updatePages

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Docs JSON Format Documentation

Table of Contents

File Structure

Source Files

JSON Format

JSON Examples

Types

Type Popups

Cross-Doc References

Description Format

### header

Types

Samples

Inline Code Areas

Custom Constructor positions

Custom Sample positions

Generating

Update Github Pages

Files

README.md

Latest commit

History

README.md

File metadata and controls

Docs JSON Format Documentation

Table of Contents

File Structure

Source Files

JSON Format

JSON Examples

Types

Type Popups

Cross-Doc References

Description Format

### header

Types

Samples

Inline Code Areas

Custom Constructor positions

Custom Sample positions

Generating

Update Github Pages