srcdoc

NAME

SYNOPSIS

srcdoc [OPTIONS] [SRC_FILES]  

DESCRIPTION

srcdoc is a source code documentation tool that extracts function information from source code and formats man pages for the functions.

Basic information is obtained from the source code itself. The function name, parameters, and return type are always available. Comments preceding the function, as well as comments within the source code, are useful starting points for a function man page. Options are available to specify if only comments in the function header, or all comments (header and comments inside the function) will be extracted.

The main steps in documentation generation are:

1. Extract function information, including header files used, function syntax, and comments from the source code file.
2. Generate an intermediate file containing the function information in a pseudo-manpage format.
3. Open an editor (vi or gvim) and edit the extracted documentation to review and complete the documentation. This step can be omitted, generating the documentation directly from the source code.
4. Re-read the intermediate text file and generate a documentation page in either HTML or man format, or both.

The man pages can be generated as troff text used by man or as HTML text which is formatted similar to typical man pages.

Formatted ASCII text documentation can also be used as the man page source. The documentation needs to have basic man type headings, such as SYNOPSIS, DESCRIPTION, RETURN VALUE, and others.

If the source code is well-commented, man pages can be reasonably complete without additional effort. With poorly commented code, srcdoc can be used as a starting point, and the descriptions can be filled in with an editor.

srcdoc has both a command line mode and a GUI mode. The command line mode is useful if the source code comments are well-formatted and complete, and you just want to format all of the functions without review. The GUI is useful for selecting functions and editing text. Most of the command line options can alternatively be entered from the GUI.

srcdoc consists of a source code function extractor and a man page formatter. The function extractor is a program that reads the output of the precompiler, finds the function definitions and the associated comments both within the function body and the comments preceding the function start, and creates an intermediate file. The man page formatter is a perl program that reads the extractor output, formats a text file for review and editing, and then creates a formatted man page.

The files created by the program are:

src_name.cpp

The C pre-processor output. Normally it's deleted immediately after use, but if the pre-processor fails, it's left so you can do a post-mortem.

src_name.dmp

The function extractor output

func_name.mtp

The intermediate text file for each function. This file is displayed (in gvim, by default) for editing. Once edited, this is the file that is used for the man page.

func_name.<#>

The man page file, where <#> is the man page section, typically 3 for function descriptions but can be set through the GUI.

func_name.html

The man page file when HTML format is selected.

<index>.html

An index HTML page containing a link to each of the HTML pages formatted.

Some time-stamp comparisons are done to avoid unneeded processing. If the function extractor output is newer than the source code file, it isn't re-generated. Command line or GUI controls can be used to specify when to generate the intermediate text. The default is to generate the intermediate file only when it doesn't already exist. Options that can be selected are to generate the intermediate text when the source code file is newer than the intermediate text file, or to always regenerate the intermediate file. Either of these options will overwrite any editing of the intermediate text that has been done, so use these with caution.

COMMAND LINE OPTIONS

The command line options are:

-c comment_type

Specifies what comments are extracted. The options are [H]eaderor [A]ll, where only the first letter is required, but the words may be spelled out. Upper and lower case are both acceptable. Only the comments in the function header are selected with the Header option, while all comments within the function, as well as the header, are extracted when the All option is selected.

-d <text_file>

Use the ASCII text document <text_file> as the man page source. The text must include some identifiers, including:

<SUBROUTINE NAME=func_name>

NAME

The function name and a brief, one-line description

SYNOPSIS

Put required include files and the function prototype here, as in the source code

DESCRIPTION

Describe the function.

and optional headers:

RETURN VALUE

BUGS

CREDITS

SEE ALSO

EXAMPLE

AUTHOR

A function description must end with:

</SUBROUTINE>

-D directives

Specify pre-compiler directives, such as include paths, defines, and other flags. If multiple directives are needed, they must be quoted so that they are seen as a single parameter.

-h

Print a brief help message explaining the command line options.

-i init_file

Specify the name of the initialization file where standard settings can be specified. See the INITIALIZATION FILE section for a description of the content and syntax of the init_file. The initialization file can contain settings for most of the command line options described in this section.

-m storage_mode

Specify the storage class as static, public, or all. Specifications can use only the first letter or abbreviations, and are case insensitive.

-n

Don't use the GUI mode.

-s tab_size

Specify the size of tabs, in spaces. It defaults to 8 spaces for a tab. This is only used for reading the comments and normalizing text that mixes leading tabs and spaces. It probably isn't needed.

-t tag_file

Specify the name of an editor tags file (for vi or emacs).

-u update_method

Specify how to update intermediate text files. The options are:

[S]ource

Always get the intermediate text from the source code

[E]dit

Use the existing, or edited, intermediate file if it exists. Generate a text file only if one does not exist for the selected function.

[N]ew

Get the intermediate file from the source if the source code file is newer than the existing intermediate file.

The first letter of the options, either upper or lower case, is sufficient, but spelling out the option is allowed. The default is the Edit option.

-v

Use verbose mode to get additional execution information. Basically this is some of my debugging statements and may not be all that enlightening.

-w

Edit the description before formatting the man page. The alternative is to create the man page directly from the source code without viewing it. This option is only useful in the command line mode (-n option).

-z

Print some CM information, like source code version numbers.

INITIALIZATION FILE

The initialization file contains settings to control user default parameters for many of the command line options or GUI controls. The items include page header settings, directory and file names, and options for controlling comment extraction, output types and other settings.

The initialization file consists of entries of the form

<Keyword>Setting</Keyword>

<Keyword name = "Value">

The Keyword options are specified below. A sample initialization file is provided with the distribution, and the GUI provides a Man Page Configuration panel for saving configurations and generating the initialization file. Either the example or the generated file can be used to get more detail on the file syntax. However, by using the GUI to generate the file, understanding the file syntax may not be necessary.

The settings that can be include in the initialization file are:

ManHeader

The ManHeader entry includes 3 options:

Section

The man page section, typically 3 for functions.

Source

The man page 'source', like 'GNU' or 'UNIX'. See "man 7 man" for a better explanation.

Manual

The name of the manual. This gets printed at the top center of the man page. Typically it's something like 'Linux Programmer's Manual'.

Author

Specify the author's name and whatever brief information you'd like in all man pages.

SrcDir

The directory that contains the source code from which to extract documentation.

TagFile

The editor (vi or emacs) tags file. See the ctags man page for details about tags.

ManDir

The directory into which the generated man pages are written.

HtmlDir

The directory into which generated HTML pages are written.

IndexFile

The name of the HTML index file which contains links to each of the HTML pages written.

PageFormat

The output page formats desired (man or HTML). Either, both or none can be specified. If not listed, defaults to both.

StorageMode

The storage modes or classes include PUBLIC, STATIC, or ALL. If not specified, defaults to PUBLIC.

Comment

The comment type setting selects between the function HEADERcomments and ALL comments, which includes headers and comments internal to the function. Header comments are those found after the previous declaration and before the start of a function. Internal comments are those found between the opening and closing curly braces. If not specified, defaults to HEADER comments.

UpdateMode

The update mode selects when comments are extracted from the source code. Comments are extracted from the source code into an extractor file when no previous extractor file exists, or when the source code file is newer than the extractor file. Then for each function, an intermediate file is generated. The Update Mode specifies when to re-create the intermediate file. The default is to generate the intermediate file only when no previous intermediate file exists, which can be specified as EDIT, meaning to always use the last edited intermediate file. To generate the intermediate file when the source code file is newer than the intermediate file, specify an update mode of NEW. To always generate the intermediate file, thus rejecting any previously written or edited file, specify SRC. This mode will destroy any editing of the intermediate file, and should be used with caution. If the source code headers are carefully formatted to contain complete documentation pages that don't require any editing, this mode can be used to keep documentation up to date with respect to the source code. Otherwise it is used primarily to reject previous editing and start from scratch at constructing documentation.

If no file is specified, a default file .srcdocrc is looked for in your home directory, then in the current working directory. If there isn't a file anywhere, a set of defaults is used. The section defaults to 3; the author name is looked up from the password file; source is set to just SRC, and the manual name is set to "Programmer's Manual". These last two are intentionally vague and probably useless.

Check the example initialization file srcdocrc file in the distribution for the file format. Or, you can run the GUI, specify the initialization information and save it to a file and not even have to be concerned with the format.

GUI OPERATION

The user interface uses perl/Tk to provide a convenient way to set all the options and control operations. There is a row of pull-down menu options across the top, a function selector on the left side, and some standard configuration options and displays on the right side. There's a status display where a list of text messages is displayed to show what's been done, and some errors, if they aren't displayed anywhere else.

The menu options are:

File

Exit

the only thing under this one.

Man Page

Edit Man Text

Edit the function selected in the Function Names panel in a gvim editor. If multiple functions are selected, they will be invoked in sequence. That is, when you close one editor, the next function will be displayed. The script hard-codes the editor; you'd have to change the perl source code to use something else, like emacs.

After editing, the man page will be generated in the Page Format selected.

The remainder of the GUI is inactive while the editor is open, because the text file is processed when you've finished editing it. There wasn't an obvious way to delay the processing of the file until the editing was complete. Other editor operations are run in the background since the output of any editing doesn't affect the program. If there are any suggestions for a good way to handle this, I'd be glad to hear from you as I find user interfaces that just go dead to be annoying.

Generate Man Page

Generate the man pages for the selected functions without editing them. Pages are generated in the selected Page Format, either man or HTML.

Set Man Dir

Specify the directory into which to write the generated man pages. A file selector will be displayed from which you can select an existing directory. It's best to use a directory named manX, where X is the man section, like 3. If not specified, writes into the current working directory. The directory is displayed in the Man Page Settings panel; you can enter the directory there also. Make sure it's an existing directory or you'll get errors in the status display and the displayed directory will revert to the last valid man directory.

Set Man Config...

A pop-up display is opened into which to specify initialization information (section, author, source and manual name) as described above. Modify, or just review, the information and then use it for man page generation, or save it to the initialization file. If you select OK, the information entered is used for this session. If you select Save, the information is written to the currently selected initialization file. Save As... lets you select a file to write the information into. Re-Init reads the configuration file and updates the display. Cancel ignores any entries made in the panel.

A series of checkbuttons is provided to select the items to be saved to the configuration file. The initial settings of these buttons reflect the contents of the previously read configuration file, which is displayed in the main menu. The items in the Man Page Configuration panel as well as the main window Man Page Settings can be selected. Those items that are selected are written to the file, and those that aren't selected are not written to the file. All items are updated in memory for the current session regardless of the check button selections.

The currently selected initialization file name is displayed in the Man Init File panel. This can be edited if you know the file that you want to use. If the file does not exist, the previous file name will be restored and a message is displayed in the Status display. To re-initialize from the settings in the currently displayed file, select the Re-Init button. If the Save button is selected, the initialization information is written to the displayed file name.

View Man Page

Opens the selected man pages currently selected in the Function Names panel. The man pages are displayed in an xterm that executes man. If multiple man pages are selected, they will all be displayed concurrently. The man page must exist in a directory that man can understand, like man3. If the man page is in the current working directory, man won't be able to find the file and display it, at least not as currently set up.

Edit Man File

Opens the currently selected function man page text in a gvim editor. This is the troff man page source, so if you want to refine the formatting, here's your chance. This is probably most useful for tweaking the bold or italics, adjust indentation and the like. This feature is not yet supplied for the HTML format. Perhaps this will be added later, but for now, you'll have to go to the directory and just edit them.

Source

These menu items are for matters dealing with the source code from which documentation is being extracted.

View Source

Opens a file selector, then brings up the selected source code files in a gvim editor. Multiple files are opened in a single gvim session. Use ':n' or ':N', or the Buffers menu to navigate between them.

Extract Comments

Opens a file selector from which source code files can be selected to extract function documentation. Then updates the Function Names listing with the functions in the selected files. The storage class (static or public) can be selected from the check buttons in the Man Page Settings panel.

Set Extraction Mode ...

Opens a panel which provides comment extraction methods for both what comments to extract, and when to extract them. Within the panel, under the Select What to Extract heading, options for All Function Comments and Header Comments Only can be selected. Only one can be selected at a time. The default is the header only option. Comments within the function body can be extracted if desired; these may only be useful to make it easier to understand what the function is doing, and will most likely need to be edited or deleted during documentation editing.

Under the Select When to Extract heading, three options are available. Always Extract is used to force comment extraction from the source code every time the source code file is selected. This will overwrite any saved intermediate text files, and thus should be used only when no previous editing of the intermediate text are desired. The Compare to Source option specifies that comment extraction is to be done only when the source code file is newer than the intermediate text file. If the intermediate text has been edited since the last comment extraction, these edits will be lost. The Extract First Time Only option is used to specify that comments are to be extracted only when no intermediate text file exists for the selected function. This is the default behavior, and safely preserves any editing that has been done. Unless the source code comments are carefully constructed to generate documentation without editing, this is the safest option to use. Others options are likely to be useful only for rejecting any edits and starting over with documentation construction.

Select Tag File

Specify the name of a tag file for use with the editor. The tags file has to already exist. See the ctags or the gctags man or info pages for more information. It's very useful for taking you to the source code while editing the man page. gctags works better with gvim.

Set CPP Directives

Opens a panel for entering include paths, defines and any other flags. The -I or -D flags are not needed for includes and defines, but for other flags specify them exactly as they should be put in the CC command line. These are used by the function extractor for running the C pre-compiler. The GNU gcc compiler is hard-coded, so if you're using some other compiler, you'll have to change the perl code.

The panel on the right side of the display contains some current settings and allows you to edit them.

Source Directory

Displays the current source code directory used by the Source menu items View Source and Extract Comments. If the directory is changed when selecting files from these menus, the directory will be updated in the Man Page Settings panel. You can modify the directory in the panel, but make sure you enter a valid existing directory. If the directory is not a valid name, a warning message is displayed and the directory name reverts to the last good value.

Man Directory

Displays the current directory into which man pages are written. You can modify the directory, but make sure you enter a valid existing directory. If the directory is not a valid name, a warning message is displayed and the directory name reverts to the last good value.

HTML Directory

Displays the directory into which to write HTML pages. You can modify the directory, but the directory must exist for the change to be accepted.

Editor Tag File

Displays the currently selected tags file. You can change the file name here, or use the Source menu to change the file. If the specified file doesn't exist, an error message is displayed and the last vailid file is restored to the entry panel.

HTML Index File

The HTML index file name used to contain links to generated pages. If no index is given, then no index file will be written. This is the only control available to suppress printing an index file when writing HTML pages.

Function Types

Select Public to extract documentation from functions that aren't static, and Static for, of course, static functions. Select both of them to get all the functions in a file.

Page Format

Select HTML or man to write pages in the selected format.

Status

Displays activity and errors not displayed elsewhere. These can't be edited. Information is highlighted with red for errors, yellow for execution information. The messages are uncolored as they age, so only the latest are colored. Not all errors are trapped here; any perl/Tk messages will still go to standard output, and there are certainly conditions that can arise that will generate perl error messages.

BUGS

The source code information is extracted with an ANSI C parser, so the original is run through the C pre-processor. Therefore, macros are reduced before the extractor sees them.

Although I've tried to be complete with the C grammar, there may be constructs and valid language extensions that aren't handled properly that could cause the extractor to fail. Let me know if you find such things and I'll try to fix them.  

CREDITS

SEE ALSO

AUTHOR

Gordon B. Aaseng, aasengg@earthlink.net, wrote this program. Contact me if you have errors or questions. If you find this useful, I'd appreciate comments or suggestions.

Index

NAME

SYNOPSIS

DESCRIPTION

COMMAND LINE OPTIONS

INITIALIZATION FILE

GUI OPERATION

BUGS

CREDITS

SEE ALSO

AUTHOR