Documentation - C API
Developer manual

This section covers VLFeat coding and documentation styles.

Coding style

This section describes the coding style of the VLFeat library.

  • No whitespaces at the end of lines. Whitespaces introduce invisible changes in the code that are detected by control version systems such as Git. Therefore whitespaces at the end of lines must be avoided.

  • Object names. Object names are capitalized and start with the Vl suffix (e.g. VlSift).

  • Descriptive variable names. Most variable names should start with a lower case letter and be capitalized, e.g., numElements. Only the following abbreviations are considered acceptable when constructing variable names: num, max, min, src, dst. The dimension of a vector is the number of elements it contains (for other objects that could be a size, a length, or a numElements). For multi-dimensional arrays, dimensions could indicate the array with each of the numDimensions dimensions.

    Example variable names
    Example Comment
    maxNumElements The maxinum number of elements.
    size The size of an object, for example the number of bytes in a memory block.
    dimension The dimension of a vector or array. Generally, this is the number of elements spanned by one scalar index
    dimensions An array of dimensions for a multi-dimensional array or tensor.
    numDimensions The number of dimensions of a multi-dimensional array or tensor.
    srcWidth The width of a source image.

  • Short variable names. For indexes in short for loops it is fine to use short index names such as i, j, and k. For example:

    for (i = 0 ; i < numEntries ; ++i) values[i] ++ ;
    

    is considered acceptable.

  • Function and methods names. Function names are lowercase with words separated by underscores and start with the vl_ prefix. Methods names in particular start with the object name. Static function names local to a module start with a _vl_ prefix instead.

    Example function and method names
    Example Comment
    vl_get_version_string A function name.
    vl_sift_get_num_frames A method name for the object VlSift.
    _vl_smooth A name of a static function local to a module.

  • Code alignment. Indendtation uses two spaces (and no tabs). Explicitly aligning blocks of code across multiple lines is not encouraged.

  • Function declarations. Functions can be declared on one or multiple lines. In the latter case, the output arguments are contained in one line. Modifiers such as VL_EXPORT and VL_INLINE are contained in the output argument line. For example:

    VL_EXPORT vl_bool vl_some_function () ;
    
    VL_EXPORT void
    vl_scalespace_delete (VlScaleSpace *self) ;
    

  • Function definition. Function definitions are similar to function declaration. However, they do not contain the VL_EXPORT modifier and are always in at least two lines. For example:

Documenting the code

Thi section describes how to document the VLFeat C library. VLFeat code contains its own in documentation Doxygen format. The documentation consists in generic pages, such as the index and the page you are reading, and documentations for each specifid library module, usually corresponding to a certain heaader file.

Documenting the library modules

A library module groups a number of data types and functions that implement a certain functionaltiy of VLFeat. Consider a module called Example Module. Then one would typically have:

  • A header or declaration file example-module.h. Such a file has an heading of the type:

    This comment block contains a file directive, causing the file to be included in the documentation, a brief directive, specifying a short description of what the file is, and a list of authors. A (non-Doxygen) comment block with a short the copyright notice follows. The brief directive should include a @ref directive to point to the main documentation page describing the module, if there is one.

  • An implementation or definition file example-module.c. This file has an heading of the type:

    This is similar to the declearation file, except for the content of the brief comment.

Documenting the library functions

Bibliographic references

VLFeat documentation makes use of a bibliographic reference database in BibTeX format (see the file docsrc/vlfeat.bib). Doxygen uses this file to interpret instances of the @cite xyz command, where xyz is a BibTeX key. For example, vlfeat.bib file contains the entry:

@inproceedings{martin97the-det-curve,
	Author = {A. Martin and G. Doddington and T. Kamm and M. Ordowski and M. Przybocki},
	Booktitle = {Proc. Conf. on Speech Communication and Technology},
	Title = {The {DET} curve in assessment of detection task performance},
	Year = {1997}}

Then the Doxygen directive @cite martin97the-det-curve generates the output [7] , which includes a link to the corresponding entry in the bibliography.