typedef documentation

[dbauszus-glx]

Modules

JSDoc comments for modules must include the module path as title and any @requires linking the page to other pages in the docs directory.

A small description should be provided to outline the module's purpose.

/**
## /user/auth

The auth module is required by the XYZ API for request authorization.

A user_sessions{} object is declared in the module to store user sessions.

@requires module:/user/acl
@requires module:/user/fromACL
@requires jsonwebtoken

@module /user/auth
*/

Functions

Comments for functions begin with the @function tag. Functions should not be anonymous. @async functions should be commented as such.

Each function comment should include an @description tag. It is recommended to use a new line for multiline descriptions.

The @param tag list should include only params used as function arguments.

Parameter properties should be included if used in the method. Any optional [property] are marked in square brackets.

A global typedef should be created for common Mapp objects.

The @return comment tag should state whether a promise is returned which may return an Error object, eg. @returns {Promise<Object|Error>}

/**
@function fromACL
@async

@description
Creates a request object for the getUser(request) method argument.
The request.email and request.password are taken from the req.body or authorization header.

@param {Object} req The request object.
@property {string} [req.body.email] The email address of the user.
@property {string} [req.body.password] The password of the user.
@property {string} [req.params.language] The language for the user.
@property {Object} req.headers The request headers.
@property {string} [req.headers.authorization] The authorization header containing the email and password.

@returns {Promise<Object|Error>}
Validated user object or an Error if authentication fails.
*/

Decorator methods

Decorator methods should always return a typedef.

@deprecated methods.

Functions no longer in use but kept with a warning for legacy configurations should be marked as @deprecated.

/**
@function Style
@deprecated

@description
The deprectaed mapp.layer.Style() method will warn if use and return the featureStyle() method which supersedes the Style() method.

@param {Object} layer 

@return {Function} featureStyle
*/

function Style(layer) {
  console.warn(`The mapp.layer.Style() method has been superseeded by the mapp.layer.featureStyle() method.`)
  return featureStyle(layer)
}

@typedef [GLOBAL]

Mapp type object should be defined as global typedefs.

Typedef properties should be defined as typedef using a dash naming convention. eg. The style object property of a layer typedef will be defined as layer-style, the theme object of a layer-style typedef will be type defined as layer-style-theme.

/**
@global
@typedef {Object} layer
A mapp-layer object is a decorated JSON layer object which has been added to a mapview.
@property {boolean} display Whether the layer should be displayed.
@property {layer-style} style The mapp-layer style configuration.
@property {layer-cluster} [cluster] Point layer cluster configuration.
*/

@example

An @example does not require a code block [```JS] definition. At examples should be reserved for codepen examples which can be run. Code blocks should be used for code syntax highlighting in the rendered markdown.

[dbauszus-glx]

I cleaned up the modules and globals which were wrongly defined in their JSDOC block.

I added stumps for the infoj-entry, layer, layer-cluster, and layer-style typedefs.

[RobAndrewHurst]

Please don't merge this until everyone in the reviewers list has looked at this.

[dbauszus-glx]

I have moved and updated the README.md for the XYZ api to the api folder.

I added the html extension to the express docs route allowing to link to static pages in the docs folder without the html extension.

I have updated the api module jsdoc and added the req, res typedef.

[dbauszus-glx]

I have updated the mapp readme with links to mapp and ui modules and core requirements for each.