Design/design.txt

   1
   2 Some random notes about the design of robodoc.
   3 This will later be turned into a proper docbook
   4 document.
   5
   6
   7
   8 Collections / Containers.
   9
  10 For most of the containers a singly linked list is used.
  11 The link to the next element is called "next" and is the
  12 first field in any structure that is stored in a linked list.
  13
  14 For instance
  15
  16 struct S {
  17     struct S* next;
  18     long   another_field;
  19     char*  aName;
  20 };
  21
  22 An anchor points to the first element in the list.
  23
  24 If this convention is used for all linked lists than it is
  25 easy to remember how to iterate through the container.
  26
  27     struct X* x_container;
  28
  29     struct X* x_iterator;
  30     for ( x_iterator = x_container;
  31           x_iterator != 0;
  32           x_iterator = x_iterator->next ) {
  33
  34     }
  35
  36 Inserting an element:
  37
  38     x_new_element->next = x_container;
  39     x_container = x_new_element;
  40
  41
  42 ========================================================
  43
  44 General Flow
  45
  46 Sourcecode  ---> [ROBODoc] ---> Document.
  47
  48 The sourcecode consists of one or more sourcefiles.
  49 The resulting document consists of one or more parts.
  50
  51 For every sourcefile that is one part.
  52 There can be additional parts. For instance
  53 for indexfiles or to pull all parts into a single document.
  54
  55
  56 > Can someone explain the differences internally of a single doc
  57 > and multi doc? At first glance, it would seem that Lua scripts
  58 > should only implement single doc because they are to be free to
  59 > do as they please, but I may be mistaken.
  60 >
  61 > Please advise.
  62
  63 The difference between singledoc and multidoc mode.
  64
  65 The whole robodoc process consists of step 3
  66 (1) The scanning of the source directory tree -- this collect the names of
  67     all the files and directories in the source directory tree.
  68     All this information is stored in a RB_Directory structure inside
  69     a RB_Document structure.
  70 (2) The analysing of all the sourcefiles -- this reads the content of
  71     all the files found in step 1 and collects all the headers found in
  72     these files.
  73     These are store in list of RB_Part structures stored inside a
  74     RB_Document structure.  For each sourcefile there is a RB_Part
  75     structure.   All the headers found in a single source file are
  76     stored as a list of RB_header structures in a RB_Part structure.
  77 (3) the generation of the documentation -- write the headers a
  78     single documentation file or mulitiple documentation files.
  79
  80
  81 The difference between single doc and multidoc can be found in step 3.
  82 The difference can be seen in most clearly in the functions:
  83 RB_Generate_SingleDoc() and  RB_Generate_MultiDoc()
  84
  85 If you look at the start of both functions they both call:
  86
  87     RB_Document_Collect_Headers( document );
  88     RB_Document_Link_Headers( document );
  89     RB_Fill_Header_Filename( document );
  90     RB_Name_Headers( document->headers, document->no_headers );
  91     RB_CollectLinks( document, document->headers, document->no_headers );
  92
  93 However before this RB_Generate_MultiDoc() calls
  94
  95     RB_Document_Determine_DocFilePaths( document );
  96     RB_Document_Create_DocFilePaths( document );
  97     RB_Document_Determine_DocFileNames( document );
  98
  99 This creates the documentation directory tree, which is a mirror image
 100 of the source directory tree, and determines for each RB_Part
 101 (sourcefile) the filename for the documentation file.
 102 The information is later used in RB_Fill_Header_Filename().
 103
 104 RB_Fill_Header_Filename() stores the name of the file a header is
 105 to be written to.  In single doc mode RB_Fill_Header_Filename() this
 106 filename is always the same (the filename specified with the
 107 --doc option).  In multidoc mode the filename can be different and is
 108 based on the name computed in RB_Document_Determine_DocFileNames().
 109
 110 In singledoc mode a single file is now opened.  For each part,
 111 the headers in this part are written to this file.  (So all
 112 headers end up in the same file).
 113
 114 In multidoc mode a new file is opened for each part, and the headers
 115 in the part are written to this file.  (So headers end up in
 116 different files).
 117
 118 In addition in multidoc mode a series of index files can be generated.
 119
 120
 121
 122 =====================================================================
 123
 124 General Flow
 125
 126 Sourcecode  ---> [ROBODoc] ---> Document.
 127
 128 The whole ROBODoc process consists of three steps: scanning,
 129 analysing, generating.
 130
 131 Scanning
 132
 133 ROBODoc scans the source directory tree. This collects the names of
 134 all the source files.
 135
 136 Analysing
 137
 138 ROBODOc analyses all the sourcefiles. This reads the content of all
 139 source files and collects all the headers.
 140
 141 Generating
 142
 143 In this step the headers are written to one or more documentation files.
 144 In addition
 145
 146 The data collected during scanning and analysing is stored in a
 147 number of structures.
 148
 149 RB_Directory, it stores the names of the sourcefiles and directories
 150 in the source direcory tree.  Files names are stored in a RB_Filename
 151 structure, directory names in a RB_Path structure.  Each RB_Filename
 152 contains a pointer (path) a RB_Path that tells in which directory a
 153 file is located.  Each RB_Path has a pointer (parent) to another
 154 RB_Path that tells of which directory is a directory located (of which
 155 directory it is a subdirectory).  The only exception is the root
 156 directory.
 157
 158 Besides the name of the sourcefile, the RB_Filename also stores the
 159 name of the documentation file.
 160
 161 For each sourcefile there is an RB_Part structure.  It contains a
 162 pointer (filename) to the RB_Filename and a list (headers) of
 163 RB_Header structure containing the headers found in the sourcefile.
 164
 165 Every RB_Header structure contains a pointer (owner) to the RB_Part
 166 structure to which it belongs.  Headers can form a hierarchy that is
 167 used to create sections and subsections in the documentation.  To
 168 store this hierarchy every RB_header structure contains a pointer
 169 (parent) to its parent header.  For instance, given the following two
 170 headers, SubModule is the parent of SubSubModule.
 171
 172 /****h* TopModule/SubModule
 173  *
 174  ****/
 175
 176 /****h* SubModule/SubSubModule
 177  *
 178  ****/
 179
 180 In the documentation this creates the sections
 181
 182 1.TopModule
 183 1.1 SubModule
 184 1.1.1 SubSubModule
 185
 186
 187 The RB_Directory and the linked list of RB_Part structures are
 188 stored in a RB_Document structure.
 189
 190 During the generation of the documentation ROBODoc tries to create
 191 cross links between the mention of a header's name (on object) and the
 192 documentation generated from that header (the documentation for the
 193 object).
 194
 195 To aid this proces there is an array of RB_link structures.  This
 196 array is sorted for quick searching.
 197
 198