docs_gm.json configuration file

docs_gm.json configuration file

To initialize a new GameMaker:Studio or GameMaker Studio 2 project type on the console:

docs_gm init

This will create a new docs_gm.json file on the user folder and will show instructions on the console to install this file on the GM project.

The docs_gm.json file looks like this:

{
        "name": "My awesome project",
	"pattern": "**/*",
	"root": "scripts",
        "parser": {
	        "warnUnrecognizedTags": true,
                "mergeDuplicateParams": true
        },
	"output": {
		"template": "basic",
		"outputFolder": "./docs/",
		"templatesFolder": "",
		"scriptPages": true,
		"folderPages": true
	},
	"scripts": {
		"markUnderscoreScriptsAsPrivate": true,
		"ignorePrivate": true,
		"undocumented": {
			"ignore": true,
			"warn": true
		},
		"mismatchingFunctionName": {
			"ignore": true,
			"warn": true
		},
		"noDescription": {
			"ignore": true,
			"warn": true
		},
		"undocumentedArguments": {
			"ignore": true,
			"warn": true
		},
		"mismatchingArguments": {
			"ignore": true,
			"warn": true
		},
		"noParamDescription": {
			"ignore": true,
			"warn": true
		},
		"noParamType": {
			"ignore": true,
			"warn": true
		},
		"functionSignatureInDescription": {
			"ignore": true,
			"warn": true
		},
                "noReturnDescription": {
			"ignore": true,
			"warn": true
		},
                "noReturnType": {
			"ignore": true,
			"warn": true
		},
                "duplicatedParams": {
			"ignore": true,
			"warn": true
		}
	}
}

ProjectConfig

• "name" (Type: string. Default: Your game maker project name)

The project's name to display

• "pattern" (Type: string. Default: "**/*")

Specifies a glob pattern that will match the files in the Game Maker project resource tree. By default, it is **/* meaning it will match anything. If you want to match resources starting with "abc_" then you can set "pattern": "**/abc_*".

• "root" (Type: string. Default: "scripts")

Defines the root directory on the GM Project resource tree. By default is the "scripts" directory. Example: "root": "scripts/tweenline" will create docs fot all the scripts on the tweenline subdirectory of the GM project.

• "parser" (Type: ParserConfig object, see below)

An object with configuration for the GML parser

• "output" (Type: OutputConfig object, see below)

An object with configuration related the the output of the documentation and the templates used.

• "scripts" (Type: ScriptValidationRules object, see below)

An object with configuration related the the validation of scripts to generate the documentation.

ParserConfig object

• "warnUnrecognizedTags" (Type: boolean. Default: true)

Will show a warning on the console when an unrecognized JSDoc tag is found on the documentation, so you can fix it.

• "mergeDuplicateParams" (Type: boolean. Default: true)

If true, the arguments with the same name will be merged.

OutputConfig object

• "template" (Type: string, Default: "basic")

The name of the template to use.

• "outputFolder" (Default: "./docs/")

The output folder

• "templatesFolder": "" (Default: "")

An optional path to a folder containing all the templates to load them locally.

ScriptValidationRules object

• "markUnderscoreScriptsAsPrivate" (Type: boolean, Default: true)

  If true, it will mark scripts names starting with underscore as private scripts

• "ignorePrivate": (Type: boolean, Default: true)

  If true, the scripts marked as private it will be excluded from the documentation. You can mark a script as private using the @private JSDoc tag or starting the name of the script with underscore with the "markUnderscoreScriptsAsPrivate" set to true. (Example: _my_private_script).

• "undocumented": (Type: ValidationRuleConfig object, see below)

This rule will fail if the script is undocumented. (Has no description, nor arguments, nor return type)

• "mismatchingFunctionName" (Type: ValidationRuleConfig object, see below)

This rule will fail if the script has a mismatching script name and "@function" JSDoc tags.

• "noDescription" (Type: ValidationRuleConfig object)

This rule will fail if the script has no description

• "undocumentedArguments" (Type: ValidationRuleConfig object, see below)

This rule will fail if the script has undocumented argument. For example, if a script has documentation for 0 arguments, but the GML code uses arguments.

• "mismatchingArguments" (Type: ValidationRuleConfig object, see below)

This rule will fail if the script has a mismatching number of arguments. For example, if the scripts has documentation for 4 arguments but the GML code uses 6 arguments.

• "noParamDescription" (Type: ValidationRuleConfig object, see below)

This rule will fail if the script has some argument without description.

• "noParamType" (Type: ValidationRuleConfig object, see below)

This rule will fail if the script has some argument without argument data type.

• "functionSignatureInDescription" (Type: ValidationRuleConfig object, see below)

This rule should detect if the "description" JSDoc tag has a function signature instead of the actual function description. This is because, when you import a GMS1 project into GMS2, the "description" tag is filled with the function generated signature.

• "noReturnDescription" (Type: ValidationRuleConfig object, see below)

This rule fails if the script has a return statement but has not documentation for the returned value

• "noReturnType" (Type: ValidationRuleConfig object, see below)

This rule fails if the script has no data type for the returned value

• "duplicatedParams" (Type: ValidationRuleConfig object, see below)

This rule fails if the script has no one or more duplicated param (argument) name.

ValidationRuleConfig object

Defines a rule to validate a script resource. If the script fails a validation rule, then the script is excluded from the documentation (If "ignore" is set to true). Optionally, you can also show a message on the console (If "warn" is set to true). Both options are true by default for all rules.

• "ignore" (Type: boolean, Default: true for all rules)

Should ignore the script if the script fails the validation rule?

• "warn" (Type: boolean, Default: true for all rules)

Should output a warning message if the script fails the validation rule?