Trans: Documented naming of exceptions

[libucw.git] / ucw / doc / docsys.txt

diff --git a/ucw/doc/docsys.txt b/ucw/doc/docsys.txt
index 733001c5e9c7be9fa892b0b1a9e5dc031472e274..b855749acea7e02c158d1cf108724bcbb41e7089 100644 (file)
--- a/ucw/doc/docsys.txt
+++ b/ucw/doc/docsys.txt
@@ -4,7 +4,7 @@ The documentation system
 ////
 Warning: if you read this file in plain-text, keep in mind the markup
 had to be escaped to show in the result as the thing you should type.
 ////
 Warning: if you read this file in plain-text, keep in mind the markup
 had to be escaped to show in the result as the thing you should type.

-You should ignore all backspaces here, or better, read the html
+You should ignore all backslashes here, or better, read the html

 version.
 ////
 
 version.
 ////
 


@@ -12,6 +12,16 @@ The ucw documentation system is based on the
 http://www.methods.co.nz/asciidoc/[ASCIIDOC] documentation formatter.
 It supports all it's markup, but it was extended slightly.
 
 http://www.methods.co.nz/asciidoc/[ASCIIDOC] documentation formatter.
 It supports all it's markup, but it was extended slightly.
 

+- <<markup,Markup extensions>>
+  * <<xrefs,Cross referencing>>
+  * <<symbols,Symbol formatting>>
+- <<extract,Header extraction>>
+  * <<scomm,Stand-alone comments>>
+  * <<defcomm,Definition comments>>
+- <<generics,Macro generics>>
+  * <<geext,Generics extraction>>
+  * <<gelink,Links to generics>>
+

 [[markup]]
 Markup extensions
 -----------------
 [[markup]]
 Markup extensions
 -----------------


@@ -81,10 +91,15 @@ Definition comments
 You can write comments documenting specific definition. Definition
 comment has the asterisks doubled. The multi-line version must be
 directly above the definition, the single-line on the same line right
 You can write comments documenting specific definition. Definition
 comment has the asterisks doubled. The multi-line version must be
 directly above the definition, the single-line on the same line right

-of the definition.
+of the definition or on a line before.

 
  void function(int parameter);  /** This is a function. **/
 
 
  void function(int parameter);  /** This is a function. **/
 

+or
+
+ /** This is a function. **/
+ void function(int parameter);
+

 or
 
  /**
 or
 
  /**


@@ -107,3 +122,47 @@ these:
 
 There is a support for building a page with list of all symbols with
 links to them. Look into `ucw/doc/Makefile` to see how to request that.
 
 There is a support for building a page with list of all symbols with
 links to them. Look into `ucw/doc/Makefile` to see how to request that.

+
+[[generics]]
+Support for macro generics
+--------------------------
+
+Some of the headers contain <<generic:,macro generics>>. Since the
+preprocessor macros look somewhat weird, the documentation extractor
+needs some help to understand them.
+
+[[geext]]
+Extraction of generics
+~~~~~~~~~~~~~~~~~~~~~~
+
+When extracting info from some header, the extractor needs to know,
+which prefix macros are used in the source file, to distinguish them
+from function calls. To inform it about them, append a comma separated
+list of such macros to the extraction command, like this:
+
+  !!filename PREFIX_MACRO_ONE,PREFIX_MACRO_TWO
+
+Then this will be correctly identified as a structure:
+
+  struct PREFIX_MACRO_ONE(struct_name) {
+    content;
+  };
+
+[[gelink]]
+Links to generics
+~~~~~~~~~~~~~~~~~
+
+Since the anchors for them are generated in a complicated manner and
+typing them in plain-text would convert them back to the original,
+with real parenthesis, there is a special pattern to create the
+symbolname part of the anchor. It looks like:
+
+  _GENERIC_LINK_|PREFIX_MACRO|symbol_name|
+
+So link to the above structure would look like:
+
+  <<struct__GENERIC_LINK_|PREFIX_MACRO_ONE|struct_name|,link text>>
+
+However, this is implemented only in the included header files (if it
+is needed, it will be implemented in the top-level documentation files
+too).