2 Some random notes about the design of robodoc.
3 This will later be turned into a proper docbook
8 Collections / Containers.
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.
22 An anchor points to the first element in the list.
24 If this convention is used for all linked lists than it is
25 easy to remember how to iterate through the container.
27 struct X* x_container;
30 for ( x_iterator = x_container;
32 x_iterator = x_iterator->next ) {
38 x_new_element->next = x_container;
39 x_container = x_new_element;
42 ========================================================
46 Sourcecode ---> [ROBODoc] ---> Document.
48 The sourcecode consists of one or more sourcefiles.
49 The resulting document consists of one or more parts.
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.
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.
63 The difference between singledoc and multidoc mode.
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
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.
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()
85 If you look at the start of both functions they both call:
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 );
93 However before this RB_Generate_MultiDoc() calls
95 RB_Document_Determine_DocFilePaths( document );
96 RB_Document_Create_DocFilePaths( document );
97 RB_Document_Determine_DocFileNames( document );
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().
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().
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).
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
118 In addition in multidoc mode a series of index files can be generated.
122 =====================================================================
126 Sourcecode ---> [ROBODoc] ---> Document.
128 The whole ROBODoc process consists of three steps: scanning,
129 analysing, generating.
133 ROBODoc scans the source directory tree. This collects the names of
134 all the source files.
138 ROBODOc analyses all the sourcefiles. This reads the content of all
139 source files and collects all the headers.
143 In this step the headers are written to one or more documentation files.
146 The data collected during scanning and analysing is stored in a
147 number of structures.
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
158 Besides the name of the sourcefile, the RB_Filename also stores the
159 name of the documentation file.
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.
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.
172 /****h* TopModule/SubModule
176 /****h* SubModule/SubSubModule
180 In the documentation this creates the sections
187 The RB_Directory and the linked list of RB_Part structures are
188 stored in a RB_Document structure.
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
195 To aid this proces there is an array of RB_link structures. This
196 array is sorted for quick searching.