MkKernel_Parser_Doc_C_API

doc : define the __parser__ attribute related to doxygen integration … More...

Collaboration diagram for MkKernel_Parser_Doc_C_API:

Macros
#define	__parser__doc_group   doc-group@OVERWRITE=DOC
	Use the doc-group section in the doxygen documentation …
#define	__parser__doc_index   doc-index=INDEX
	Add index doc-index to the doc-group section …
#define	__parser__doc_name   doc-name=NAME
	Add name doc-name section to the doc-group section …
#define	__parser__doc_no   doc-no
	Do not write a doc entry into the doxygen documentation …
#define	__parser__global__doc_force   doc-force@LIST=CLASS_or_PACKAGE@INDEX@?local?
	Force the doyygen-index to be build even if no function is available …
#define	__parser__global__doc_db   doc-db=DIRECTORY
	Set directory for external documentation lookup…
#define	__parser__doc_sort   doc-sort=DICTIONARY
	dictionary doc-sort of the function in the documantation…

Detailed Description

doc : define the __parser__ attribute related to doxygen integration …

Define the __parser__(doc-XXX=…) function…, __parser__global__(function:doc-XXX:…) or the __parser__global__(function:…) attribute.

‍The doc-attribute is used to integrate the All-Language-Compiler (ALC) code into the doxygen-documentation.

The documentation is splitted into 3 parts called doc-index, doc-group and doc-name:

• The doc-index and the doc-name have as default the _ignore_ value.
• The doc-group has as default the Misc value.
• The value should be a camel-case string defined as [A-Z][a-zA-Z0-9].

The doc-attribute create a doxygen-item:

• The doc-index and the doc-group create a @addtogroup item
• The doc-name create a @name item

example of the doc-attribute integration into doxygen:

@addtogroup MyClassC_DocIndex_LNG_Api
@{
  @addtogroup MyClassC_DocIndex_DocGroup_LNG_Api
  @{
    @name DocName - ...
    @{
      ...
    @}
  @}
@}

The following restrictions are used by the doc-attribute:

• If the doc-index or doc-group is _ignore_ the doxygen-item disappears.
• If the doc-name is _ignore_ the doxygen-section is set to MyClass_?MyIndex?_MyGroup_LNG_Api - ...
• The All-Language-Compiler (ALC) compiler decide if the doxygen-item is created or not.

The C __parser__ extension does not read the already available doxygen documentation and doc-index and doc-group have to fit into the existing doxygen structure.

• The doc-index create a new doxygen-group-definition with doc-group as sub-group.
• ONLY the All-Language-Compiler (ALC) created code is using the doc-attribute feature.
• The code written by the programmer must be manually added to the correct group.

example: the doc-attribute integration into doxygen with manually added code:

@defgroup MyClassC_MyIndex_C_API  "MyIndexDocStr"
@{
  @defgroup MyClassC_MyIndex_MyGroup_C_API  "MyGroupDocStr"
  @{
    __parser__push__(doc-group=MyGroup,doc-index=MyIndex);
      ...
      void my_func_(void);
      ...
    __parser__pop__;
  @}
@}

• Only the All-Language-Compiler (ALC) created code will be decorated by doxgen-items.

example: the overload-feature (c_Overload.tcl) create the following code for the MkErrorNext function:

@addtogroup MkErrorC_Class_Introspection_C_API
@{
  @name MkErrorC_Class_Introspection_C_API - overload
  @{
   // doc-key: MkErrorC,MkErrorC-Class-Introspection,oc_
     #define MkErrorNext_0E()       MkErrorNext(&MkERROR)
     #define MkErrorNext_1M(m)      MkErrorNext(MkErrorFORMAT_1M(m))
  @}
@}

Macro Definition Documentation

__parser__doc_group

#define __parser__doc_group   doc-group@OVERWRITE=DOC

Use the doc-group section in the doxygen documentation …

Every function is added to a doc-group section, if no doc-group section is set the default Misc is used.

• To disable the default Misc value use the _ignore_ value.
• For detail information about doxygen integration use: doc-index

Definition

scope	global or function
usage	__parser__global__(FUNCTION:doc-group=DOC);
usage	__parser__(doc-group=DOC) FUNCTION ...
see also	__parser__(doc-no); __parser__(doc-index)

Example

__parser__(doc-group=Log,doc-index=_ignore_)
MK_EXTERN MK_STRN MK_DECL MkLogTimeoutE (
  enum MkTimeoutE val
);

Definition at line 1977 of file parser_mk.h.

__parser__doc_index

#define __parser__doc_index   doc-index=INDEX

Add index doc-index to the doc-group section …

Sometimes there are too many functions in a class for a clear presentation. With the doc-index it is possible to add an additional index-level.

The doc-index is created ONLY when a function is available. If you want the doc-index to always be created, use the global doc-force option such as __parser__global__(doc-force=MyClass@MyIndex);.

• If doc-index is _ignore_ (the default value) than the doc-group with default value Misc is used.
• For detail information about doxygen integration use: MkKernel_Parser_Doc_C_API

Definition

scope	global or function
usage	__parser__global__(FUNCTION:doc-index:INDEX);
usage	__parser__(doc-index=INDEX) FUNCTION ...
see also	doc-group; doc-name; doc-no

Definition at line 1999 of file parser_mk.h.

__parser__doc_name

#define __parser__doc_name   doc-name=NAME

Add name doc-name section to the doc-group section …

Sometimes a function should be added to the main-doc-class like MkBufferC_C_API, but in a separate namespace to group the functions together or to improve readability.

• The doc-name is adds an @name section to the documentation
• For detail information about doxygen integration use: MkKernel_Parser_Doc_C_API

If the All-Language-Compiler (ALC) decides to add a @name section, for example to summarize the inline or overload functions, doc-name is the default-name. With _ignore_ the doc-group is used like MyClassC_MyGroup_C_API.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:doc-name:NAME);
usage	__parser__(doc-name=NAME) FUNCTION ...
see also	doc-group; doc-index; doc-no

Definition at line 2018 of file parser_mk.h.

__parser__doc_no

#define __parser__doc_no   doc-no

Do not write a doc entry into the doxygen documentation …

The doc-no feature is usefull if an internal or hidden function is visible to the public-api but only for testing purpose.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:doc-no=yes);
usage	__parser__(doc-no) FUNCTION ...
see also	doc-group; doc-index

Example

disable documentation for test-function

__parser__global__(hide-rx=^MkSys);
....
__parser__(keep,doc-no)
MK_EXTERN enum MkErrorE MK_DECL MkSysGetPid (
  MK_OBJ const fmtobj,
  MK_I32 * pid_out
);

Definition at line 2043 of file parser_mk.h.

__parser__doc_sort

#define __parser__doc_sort   doc-sort=DICTIONARY

dictionary doc-sort of the function in the documantation…

All function belonging to a group ar sorted regarding the doc-sort. If the doc-sort is not set then an order is created. by default the character-set-sort-order (TCL: lsort -ascii) is used.

Definition

usage	__parser__global__(doc-sort=DICTIONARY);
example	__parser__global__(doc-sort=ils-2);
see also	doc-group; doc-index

Definition at line 2120 of file parser_mk.h.

__parser__global__doc_db

#define __parser__global__doc_db   doc-db=DIRECTORY

Set directory for external documentation lookup…

This attribute is only used if a native library without PLMK (Programming-Language-Micro-Kernel)-Support is used as input and the native documentation-format can not be used by doxygen.

The external-documentation of a native-library is using usually an other documentation-format as doxygen.
A documentation-preprocessor have to be written for any external documentation and is required to transfer the external-documentation into a format readable by doxygen.
Finally the external-documentation put into the doc-db database and a All-Language-Compiler (ALC) tool like c_NativeDoc.tcl is used to build the final doxygen documentation.

• For libconfig the the tool libconfig_2_docdb.tcl is part of the LibLcConfig package.
• For libsqlite3 the the tool libsqlite3_2_docdb.tcl is part of the LibSq3Lite package.

The format of the documentation-database is easy, a directory with a file for every documentation item.

Definition

usage	__parser__global__(doc-db=DIRECTORY);
example	__parser__global__(doc-db=doc_db.dir);
see also	MkKernel_Parser_Doc_C_API

Example

LibLcConfig - the documentation directory with file listing

// library header and parser input
__parser__global__(doc-db=doc_db.dir);
 
// the "doc-db" directory
doc_db.dir
 
// the toplevel documentation item (doxygen: /section)
doc_db.dir/chapter-list
doc_db.dir/chapter-The C API-section-list
doc_db.dir/chapter-The C API-func-list
doc_db.dir/chapter-The C API
...
 
// the "section" is below the "chapter" (doxygen: /subsection)
doc_db.dir/section-Why Another Configuration File Library?
...
 
// the "func" and the "section" define the "chapter" (doxygen: /func)
doc_db.dir/func-ConfigWriteFile
...

Definition at line 2107 of file parser_mk.h.

__parser__global__doc_force

#define __parser__global__doc_force   doc-force@LIST=CLASS_or_PACKAGE@INDEX@?local?

Force the doyygen-index to be build even if no function is available …

The __parser__(doc-index=MyDocIndex); will ONLY be build if a function is available. If the build should always be done use the __parser__global__(doc-force=MyClass@MyDocIndex); global option. If the optional third option is the string local than a local-reference will be used as source of documentation like ${class}_${doc(R)}_${lng}_API rather than ${class}_${doc(R)}_C_API. A local-reference is usefull if the Target-Programming-Language (TPL) language documentation differ.

Definition

usage	__parser__global__(doc-force=CLASS_or_PACKAGE@INDEX@?local?);
example	__parser__global__(doc-force=MqMsgque@Item);
see also	doc-group; doc-index

Definition at line 2059 of file parser_mk.h.