Objective

  • Semantic annotations for source code
  • Able to integrate with or generate tags for
    • splint
    • doxygen

Syntax

Operators

Operator Meaning
! error
? warning

Attributes

Tag splint doxygen Meaning
in @in @param [in] Input parameter
out @out @param [out] Output parameter
inout @in @out @param[in,out]  
nullin @null - Null input is ok
nullout     Null output is ok
zeroin     Zero input is ok
zeroout     Zero output is ok
pointer     Target is a pointer type

Example

Plain C

extern int
handle_init(void* handle);

Commented C

/*
 * Initialize the handle.
 * 
 * Returns non-zero on error.
 */
extern int
handle_init(
    void* handle /* pointer to handle, can be null */
    );

splint

/* Initialize the handle.
 * 
 * Returns non-zero on error.
 */
extern int
handle_init(
    /*@out*/ /*@null@*/ void* handle /* pointer to handle */
    );

Doxygen

/**
 * Initialize the handle.
 *
 * @return non-zero on error
 */
extern int
handle_init(
    void* handle /**< [out] pointer to handle, can be null */
    );

splint and Doxygen

/**
 * Initialize the handle.
 *
 * @return non-zero on error
 */
extern int
handle_init(
    /*@out*/ /*@null@*/ void* handle /**< [out] pointer to handle, can be null */
    );

GAC

/** Initialize the handle. */
extern int /**< @!notzero */
handle_init(
    void* handle /**< @inout @nullin @?nullout @pointer to handle */
    );

Notes

  • Aim to document only what can't be expressed in code

SideBar