Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

Comment pass-through

Qidlc identifies code comments as a Doxygen comments, qidl-comments] or ordinary comments. Doxygen comments and qidl-comments are passed through to generated C and C++ header files. When documenting interface methods, Doxygen comments are generally preferred.

Doxygen comments

When a method is documented with the Doxygen syntax, qidlc will attempt to translate the documentation to the target language in any output files. For example, since C does not have any built-in support for objects, every generated method contains a pif parameter (Pointer to InterFace). When generated a C header, qidlc will inject documentation for the pif parameter. When generating a C++ header, it will not.

Qidl-comments

The compiler supports a second comment pass-through mechanism that predates support for Doxygen comments, called qidl-comments. A qidl-comment always starts with the word qidl and its syntax is explained in the qidl-comment sytnax section below. For comment pass-through to work properly, the external preprocessor must preserve comments in the preprocessed output. If using the default preprocessor, the appropriate option is specified automatically, but if specifying a custom preprocessor with the -p option (see Command-line usage), the preprocessor option to preserve comments must also be specified. For many preprocessors, the option is -C, so the appropriate option to qidlc is -pa=-C. If the preprocessor is not properly set to preserve comments, comment pass-through from IDL will not work properly.

Qidl-comment limitations

Comment pass-through has the following limitations and known issues:

  • Comments for pass-through may only appear at the global scope, within a module, or within an interface.
  • Nested comments (those in #includes) only work if they are at the top level (not within a module or interface).
  • Using preprocessor (cpp) under Win32 can result in blank lines in comments when the source file uses DOS-style end-of-lines (\r\n), because some versions of cpp treat \r as a newline, which results in \r\n becoming \n\n. To work around this problem, use a different preprocessor (such as armcc or cl), or change the source to use Unix-style end-of-lines (\n).

Qidl-comment syntax

A comment marked for pass-through begins with the keyword qidl occurring at the start of the comment, with no whitespace. Single-line (C++-style) and multi-line comments are both acceptable.

/*qidl  %  */
//qidl  % 

The qidl keyword is followed by zero or more whitespace-delimited name=value attribute pairs. Quotes are not used. Whitespace is allowed around the equals sign, but cannot appear within a name or value. A name without a value is a preset that expands to a number of attribute assignments. Once an attribute is set, it retains that value until it is changed. Each attribute has a default value to which it is set at the beginning of each file. Attributes are scoped per source file, and are processed in order. The same attribute may be specified more than once in a single attribute list, but only the last value assigned will be retained. The qidl keyword and all attribute names and values are case-sensitive.

The end of the name=value pairs is indicated with the % character. The body of the comment starts with the first character following the %. A newline can be used instead of a %, in which case the comment starts at the beginning of the next line. Empty (zero-character) comments are not passed through, but all-whitespace comments are.

Examples (both examples are equivalent if they are not indented):

//qidl location=top target=all % This banner goes at the top 
/*qidl location=top target=all This banner goes at the top*/ 

A short comment form may be used when no attributes need to be changed. Multi-line comments of this form begin with /%, and single-line comments begin with //%. These are equivalent to /qidl% and //qidl%, respectively, except that in the short form the % may not be omitted.

For example:

//qidl location=top target=all 
//% This banner goes at the top

Qidl-comment attributes

The following are the qidl-comment attributes:

Name Values Default Description
location top, bottom bottom Indicates where the comment should be in the file
nested true, false false Pass-through comment even when included.
target c, cxx, c++ The backend(s) that comments apply to
fold true, false false If duplicates, comment blocks are eliminated

Qidl-comment fold

A comment block is defined as a continuous sequence of qidl-comments. For example:

//qidl fold=true % CommentBlockA 
//%CommentBlockA 
//%CommentBlockA
// 
//%CommentBlockB 

Comment blocks are considered duplicates if all text is identical, and does not depend on what file the comment originated from.

Qidl-comment resets

The following qidl-comment presets are recognized. Each preset expands to and is, therefore, equivalent to the specified set of attributes.

  • default: The default values for all parameters.

    • location=bottom
    • nested=false
    • target=c,cxx,c++,
    • fold=false

  • c-comment Alias for default

  • copyright: Standard behavior for copyrights. Duplicates are removed.
    • location=top
    • nested=false
    • target=all
    • fold=true