Motr Sample Module

Detailed functional specification template. More...

Data Structures
struct	dld_sample_ds1

Functions
M0_INTERNAL int	dld_sample_sub1 (struct dld_sample_ds1 *param1, bool read_only)

Variables
unsigned int	dld_bad_example

Detailed Description

Detailed functional specification template.

This page is part of the DLD style template. Detailed functional specifications go into a module described by the Doxygen @defgroup command. Note that you cannot use a hyphen (-) in the tag of a @defgroup.

Module documentation may spread across multiple source files. Make sure that the @addtogroup Doxygen command is used in the other files to merge their documentation into the main group. When doing so, it is important to ensure that the material flows logically when read through Doxygen.

You are not constrained to have only one module in the design. If multiple modules are present you may use multiple @defgroup commands to create individual documentation pages for each such module, though it is good idea to use separate header files for the additional modules. In particular, it is a good idea to separate the internal detailed documentation from the external documentation in this header file. Please make sure that the DLD and the modules cross-reference each other, as shown below.

See also

The Motr Sample DLD its Functional Specification and its Threading and Concurrency Model

Function Documentation

dld_sample_sub1()

M0_INTERNAL int dld_sample_sub1	(	struct dld_sample_ds1 *	param1,
		bool	read_only
	)

Subroutine1 opens a foo for access.

Some particulars:

• Proper grammar, punctuation and spelling is required in all documentation. This requirement is not relaxed in the detailed functional specification.
• Function documentation should be in the 3rd person, singular, present tense, indicative mood, active voice. For example, "creates", "initializes", "finds", etc.
• Functional parameters should not trivialize the documentation by repeating what is already clear from the function prototype. For example it would be wrong to say, "@param read_only A boolean parameter.".
• The default return convention (0 for success and -errno on failure) should not be repeated.
• The @pre and @post conditions are preferably expressed in code.

Parameters

param1	Parameter 1 must be locked before use.
read_only	This controls the modifiability of the foo object. Set to true to prevent modification.

Return values

return

value

Precondition

Pre-condition, preferably expressed in code.

Postcondition

Post-condition, preferably expressed in code.

Variable Documentation

dld_bad_example

unsigned int dld_bad_example

This is an example of bad documentation, where an external symbol is not documented in the externally visible header in which it is declared. This also results in Doxygen not being able to automatically reference it in the Functional Specification.

Definition at line 624 of file dld-template.c.