HOWTO: Setup A Start-Off To Documenting Your Source Code

In this topic

Required Result
The Solution
The Result

HandyFile Find and Replace is so flexible that it can be used in any activity. In this example we shall consider how a developer can create an HTML file to be the starting point of creating a documentation for the C++ source code.

We shall work on the C++ source files (.cpp).

Required Result

We want to receive an HTML file on output, formatted as per following rules.

• Format individual functions as tables.
• Any function should be formatted in the following way:
  
  

  Class: class_name
  Function: function_name
  Parameters: list of parameters
  Returns: return_type
  Description: method_description

• The following styles should be used for formatting:

  Element	Style name
  Entity name ("Class", "Function", etc.)	ename
  Source code entry ("class_name", "function_name", etc.)	scname

  
  
• The method prototype section and the Description section should reside within individual cells.

The Solution

1. Specify the folder in which you want to find files. For example: C:\Projects\MyLibrary
2. Set mask(s) of the files that you want to find. For example: *.cpp
3. Switch on the regular expressions.
4. It is best to first try your regular expression that will be used to search for C++ methods using the Regular Expression Laboratory. The expression would look like follows (line-break is inserted for better readability only):
   
   

([\w\d\_]*\s@{\&|\*}?)\s@([\w\d\_]+)\:\:
                       ({{\~?[\w\d\_]}|{operator.}}+)\(([^\)]@)\)[^\;]

where
    ([\w\d\_]*\s@{\&|\*}?)
                     matches the function return type. 
                     The * operator indicates that 
                     the return type specification may not exist.
                     The expression \s@{\&|\*}? allows any indirection. 
                     (first stored expression);

    ([\w\d\_]+)      matches the class name 
                     (second stored expression);

    ({{\~?[\w\d\_]}|{operator.}}+)
                     matches the function name, 
                     which may be the destructor \~?
                     or operator {operator.}
                     (third stored expression).

    (.@)             matches the function parameters
                     (fourth stored expression).

    [^\;]            disallows matching function calls.

5. We will have to reformat the stored expressions to match the prerequisites. Please note that we can still use the replacement strings for collecting even if searching. As there may be several lines of text, we open the Multiline editor by clicking the button . The following text will conform to the specifications:
   
   

   <table>
   <tr><td>
   <span class="ename">Class: </span><span class="scname">\2</span><br>
   <span class="ename">Function: </span><span class="scname">\3</span><br>
   <span class="ename">Parameters: </span><span class="scname">\4</span><br>
   <span class="ename">Returns: </span><span class="scname">\1</span><br>
   </td></tr>
   <tr><td>
   <h1>Description</h1>
   </td></tr>
   </table>
   
   where
       \2 is the stored class name;
       \3 is the stored function name;
       \4 is the stored function parameter set;
       \1 is the stored function return type.

6. Go to the Collect tab and check the Collect... option. 
7. Set the path to the collector file, for example: C:\Projects\MyLibrary\doc.html.
8. Set the Collected text to Replacement text, and Text entry separator to New line.
9. Click the Search button.

The Result

The following block is a part of the generated collector file for the MFC source:

<table>
<tr><td>
<span class="ename">Class: </span><span class="scname">CListView</span><br>
<span class="ename">Function: </span><span class="scname">DrawItem</span><br>
<span class="ename">Parameters: </span><span class="scname">LPDRAWITEMSTRUCT</span><br>
<span class="ename">Returns: </span><span class="scname">void</span><br>
</td></tr>
<tr><td>
<h1>Description</h1>
</td></tr>
</table>

<table>
<tr><td>
<span class="ename">Class: </span><span class="scname">CListView</span><br>
<span class="ename">Function: </span><span class="scname">OnChildNotify</span><br>
<span class="ename">Parameters: </span><span class="scname">UINT message, WPARAM wParam, LPARAM lParam,
LRESULT* pResult</span><br>
<span class="ename">Returns: </span><span class="scname">BOOL</span><br>
</td></tr>
<tr><td>
<h1>Description</h1>
</td></tr>
</table>