Automatic documentation of procedures and methods

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Overview
Automatic documentation
Parameters
What is included in the comments?
Remark: deleting parameters
Assisted input
Assisted input on the procedures and class methods

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

Automatic documentation of procedures and methods

Overview

To simplify the maintenance or the use of existing code by other developers, WINDEV, WEBDEV and WINDEV Mobile propose an automatic documentation for the procedures (or class methods).

This automatic documentation corresponds to a set of comments. These comments are generated:

When creating a new procedure or method.
Versions 21 and later
You have the ability to generate the comments in the window that is displayed when creating a procedure or method ("Generate a header comment" option). The generated comments will comply with the automatic documentation parameters.
New in version 21
You have the ability to generate the comments in the window that is displayed when creating a procedure or method ("Generate a header comment" option). The generated comments will comply with the automatic documentation parameters.
You have the ability to generate the comments in the window that is displayed when creating a procedure or method ("Generate a header comment" option). The generated comments will comply with the automatic documentation parameters.
Via (found in the upper-right corner of the code window of procedure). This icon is used to generate or to delete a set of comments for the current procedure.

You can also:

Automatically synchronize the generated comments according to the syntax of the procedures. Modifying the syntax automatically updates the associated comments (during the backup).
Use the assisted input when writing the call to the documented procedures or methods. For more details, see Assisted input.

Automatic documentation

Parameters

To configure the automatic documentation:

On the "Home" tab, in the "Environment" group, expand "Options" and select "Options of the code editor".
Display the "Doc." tab.

Important: Each block of comments must comply with the format presented below. Especially, the description of each parameter as well as the description of return value must be done on a single line. Otherwise, offsets may appear.

What is included in the comments?

The comments of a function or procedure can contain the following elements:

Summary: the corresponding comment is as follows:
Header for describing the procedure: the corresponding comment is as follows:
Call syntax: the corresponding comment is as follows:
Details of parameters: the corresponding comment is as follows:
Automatic timer: the corresponding comment is used to describe the automatic timer defined for the function or for the procedure:
Automatic management of errors and exceptions: the corresponding comment is used to describe the management mode of errors and exceptions (defined via the "If Error" link in the header bar of procedure). For example:
Remark: the corresponding comment is as follows:
Example: the corresponding comment is as follows:
Mark indicating that the procedure must be documented: the corresponding comment is as follows:

Remark: deleting parameters

If a parameter is specified in the procedure syntax then if it is deleted, the reference to the parameter is still visible in the "Details of parameters" section of comments.

The text typed by the developer regarding the parameter must be manually deleted by the developer (limits the risks of deletion by "mistake").

The option "Synchronize the comments with the syntaxes of the procedures" is used to keep updated comments regardless of the modifications performed.

Assisted input

Assisted input on the procedures and class methods

If the parameters of a procedure have been documented and if the assisted input is available in the code editor, when typing the call to the procedure, the syntax and the description of parameters are displayed in a tooltip. For example:

Documentation of the procedure
Assisted input on the procedure

The mechanism of assisted input for the procedures and methods is identical to the mechanism used for the WLanguage functions. For more details on the assisted input parameters in WINDEV, WEBDEV or WINDEV Mobile, see Assisted input for the WLanguage functions.