Browse and Doc It

Overview

This Embarcadero RAD Studio IDE plug-in allows you to document and browse your code from within the IDE.

The supported IDEs are as follows:

  • Embarcadero RAD Studio XE;
  • Embarcadero RAD Studio XE2;
  • Embarcadero RAD Studio XE3*;
  • Embarcadero RAD Studio XE4*;
  • Embarcadero RAD Studio XE5*;
  • Embarcadero RAD Studio XE6*;
  • Embarcadero RAD Studio XE7;
  • Embarcadero RAD Studio XE8*;
  • Embarcadero RAD Studio XE 10 Seattle;
  • Embarcadero RAD Studio XE 10.1 Berlin;
  • Embarcadero RAD Studio XE 10.2 Tokyo.

* Note: The code supports these version of the IDE but unfortunately I do not have these IDEs so cannot compile the DLLs. Please refer to the article Compiling and installing my experts and wizards… for instructions on how to compile the code for the missing IDEs (you will need the VirtualTreeView components to compile this yourselves).

Installation

Browse And Doc It is design to be loaded as a DLL expert. You can use GExperts’ (http://www.gexperts.org/) Experts Manager to do this, my Multi-IDE Expert Manager or follow the instructions below:

  • From the Start menu select Run;
  • Enter regedit and press <Enter>;
  • Browse to the key HKCU\Software\Embarcadero\BDS\19.0\ (change the path number for your IDE);
  • If there is no key called Experts then you will need to create one;
  • Under Experts create a new string as follows:
    • Key = BrowseAndDocItXE102;
    • Value = Drive:\Path\BrowseAndDocItXE102.DLL.

On reloading the IDE the IDE Experts should appear in the IDE.

For more information on installing this expert please refer to my post Compiling and Installing my experts and wizards….

Browse And Doc It Help

This help file contains information about what’s on the screen in Browse And Doc It, what is displayed in the HTML documentation and how to use this tool. See the section on Browse And Doc It Comment Format below for information on the layout of the comment blocks and the tags that can be used.

Module Explorer

The module explorer allows you to browser your currently open source code via a tree representation of the declarations. This browser also shows you any errors, warnings, hints and documentation conflicts that should be resolved. These conflicts can be switched on and off in the options. Also various tags can be summarised and displayed in the tree view – these can also be configured in the options.

The tree view can be customised to display syntax highlighted information. This can be switched on in the options – it is off by default.

Selecting a declaration in the browser will take you to the location in the source code. Pressing the <Enter> in the browser will focus the source code editor and Ctrl+Shift+Enter+<Enter> from the code editor will focus the browser.

Additionally, pressing <Enter> with any of the key modifiers Shift, Ctrl or Alt will bring the selected declaration in the browser into focus in the editor but the browser will still remain the focused control.

If there are any special tags in a declaration comment or within the implementation of a method then these tags will be displayed at the top of the tree view. Selecting a tag will take you to its location.

Any comments associated with a declaration or tag in the code can be shown in a popup hint window which can be configurable to be shown from the options dialogue.

At the top of the module explorer is a small toolbar which allows you to switch on and off the scope of items to be displayed in the treeview. The icons are as follows:

Icon Description
Show or hide local elements.
Show or hide private elements.
Show or hide protected elements.
Show or hide public elements.
Show or hide published elements.
Enabled or disable the syntax highlighting.
Enabled or diable showing the display of hint windows.
Show or hide documentation conflicts.
Show or hide errors.
Show or hide warnings.
Show or hide hints.
Show or hide methods.
Show or hide properties.
Show or hide constants.
Show or hide variables.
Show or hide types.

Finally the browse allows the contents to be filtered. To filter the contents, make the browser have focus and type a regular expression as a search criteria.

Insert Method Comment

This option inserts a comment based on the preceding method declaration relative to the current cursor position. It will automatically list all parameters and returns values. If the method name matches a method description in the options dialogue, that description will be entered in the comment automatically.

If in the options you have pre and post condition checking enabled for methods then you will have to add a pre-condition and a post-condition.

If you try and add a method comment to an existing method with a comment, Browse And Doc It will prompt you if you would like to update the existing comment. All descriptions and tags are retained from the existing comment.

This can be invokes using the keyboard stroke Ctrl+Shift+Alt+M.

Please note that in this example we are using pascal. Browse and Doc It will create comments appropriate to the language you are using if there is a supporting parser. See below for the parsers that are currently available.

Insert Property Comment

This option inserts a comment based on the preceding property declaration relative to the current cursor position. It will automatically list all parameters and returns values.

If in the option you have pre and post condition checking enabled for properties then you will have to add a pre-condition and a post-condition.

If you try and add a property comment to an existing property with a comment, Browse And Doc It will prompt you if you would like to update the existing comment. All descriptions and tags are retained from the existing comment.

This can be invokes using the keyboard stroke Ctrl+Shift+Alt+P

Like with methods, please note that in this example we are using pascal. Browse and Doc It will create comments appropriate to the language you are using if there is a supporting parser. See below for the parsers that are currently available.

Insert Comment Block

This options inserts a block pascal comment. This is useful for module comments where you wish to descripton a large amount of information.

This can be invokes using the keyboard stroke Ctrl+Shift+Alt+B.

Like with methods, please note that in this example we are using pascal. Browse and Doc It will create comments appropriate to the language you are using if there is a supporting parser. See below for the parsers that are currently available.

Insert Line Comment

This options inserts a line pascal doc comment. This is useful for short comments for the likes of variables, types and classes.

This can be invokes using the keyboard stroke Ctrl+Shift+Alt+L.

Like with methods, please note that in this example we are using pascal. Browse and Doc It will create comments appropriate to the language you are using if there is a supporting parser. See below for the parsers that are currently available.

Insert InSitu Comment

This is most useful for very small comments, say within a uses clause to note why you are using a unit.

This can be invokes using the keyboard stroke Ctrl+Shift+Alt+I.

Like with methods, please note that in this example we are using pascal. Browse and Doc It will create comments appropriate to the language you are using if there is a supporting parser. See below for the parsers that are currently available.

DUnit

This allows you to create DUnit projects and module or add to tests to an existing DUnit project and module for public and published class methods and properties. There are a few options in the dialogue as follows:

  • DUnit Project: Here you can select the name for a new DUnit project or select from the drop down list of existing DUnit projects
    in the project group.
  • DUnit Unit: Here you can select the name for a new DUnit unit or select from the drop down list of existing DUnit units
    in the previously selected existing project.
  • Base Class: Here you can specify the base class for the test classes.
  • TestSuite Name: Here you can specify a name for the test suite so as to group your tests into logical units.

Finally just select the methods and / or properties of the classes you wish to create tests for and the units and projects files where necessary will be created or added to. Note: you can added new classes to both exist units and also extend existing class test with new methods. If you wish to create a second or third test for the same method, clashing names will be appended with a number in order to keep the new methods or properties unique.

NOTE: At the moment only pascal code can be used to generate DUnit tests.

Profiling

This dialoge allows you to insert into the methods of your code instrumentation profiling code at the start and end of each selected procedure. It also allow you to remove the instrumentation once you are finished.

It was design around the Profiler.pas module that can be found in the Profile Viewer.

The code to be insert should be typed into the area at the bottom of the dialogue and needs to contain the following 2 macros that get expanded for each method:

  • $METHODNAME$: This macro is replaced by the class and method name of the specific method;
  • $METHODCODE$: This is the position in the profiling code where the body of the method should appear.

A prerequisite is that the BEGIN and END of the method should be on their own lines without any other statements.

The following listing of code shows the results of the above application of the profiling code.

The Profiler.pas module is fairly basic in its functionality. Once your project includes the module and the PROFILECODE compiler definition is created, then where the profiling code is inserted in a method, these calls will be logged. On closing the application, the applicationname.profile file will be written which can be viewed with the above mentioned Profile Viewer.

It should also be noted that the type of instrumentation profiling DOES have a performance impact on your application. You do not need to remove the profiling code from the application for release, just remove the PROFILECODE compiler definition from the project and re-build ALL units in your project.

Documentation

This option allows you to generate documentation from you code project. At the moment only HTML documentation can be generated but hopefully in the not to distant future I will implement RFT, Win32 Help and HTML Help documentation engines.

There are some options at the bottom of the documentation dialogue which allow you to determines the scope of the elements which are output into the documentation.

The documentation for a project is output to a directory called Documentation off the folder containing the project file. In that directory is another sub-directory called HTML in which the HTML documentation is output.

At the end of the documentation generation process the HTML summary is opened in your default browser.

The layout and style of the HTML documentation can be altered by changing the 2 style sheets in the Styles directory off the location of the Browse and Doc It DLL/BPL. These are always copied to the destination documentation directories. They do not exists until after the first time you attempt to generate documentation.

Options

The options for Browse and Doc It have grown since Pascal Doc and are now broken down into the following sections:

General Options

There are eight pages of options for Browse and Doc It as follows:

The general option for Browse and Doc It are as follows:

Options Description
Draw Syntax Highlighted Module Explorer Enabled or disables the syntax highlighting of the module explorer tree view.
Show comments in the hints Enabled or disables the display of hint windows showing the comments associated with the element in the tree view the mouse is over.
Show Module Errors Hides or shows the errors found in the code currently being browsed.
Show Module Warnings Hides or shows the warnings found in the code currently being browsed.
Show Module Hints Hides or shows the hints found in the code currently being browsed.
Show Documentation Conflicts Hides or shows the documentation conflicts found in the code currently being browsed.
Show Undocumented Types Hide or shows a list of undocumented types found in the code being browsed.
Show Undocumented Records Hide or shows a list of undocumented records found in the code being browsed.
Show Undocumented Objects Hide or shows a list of undocumented objects found in the code being browsed.
Show Undocumented Classes Hide or shows a list of undocumented classes found in the code being browsed.
Show Undocumented Interfaces Hide or shows a list of undocumented interfaces found in the code being browsed.
Show Undocumented Variables Hide or shows a list of undocumented variables found in the code being browsed.
Show Undocumented Constants Hide or shows a list of undocumented constants found in the code being browsed.
Show Undocumented Fields Hide or shows a list of undocumented fields found in the code being browsed.
Show Undocumented Class Types, Vars and Consts Hide or shows a list of undocumented class types, variables and constants found in the code being browsed.
Show Undocumented Module Hide or show whether there is a missing module documentation comment.
Show Missing Module Date Hide or show whether there is a missing module documentation date tag.
Show Check Module Date Hide or show whether there is a invalid or incorrect module documentation date tag.
Show Missing Module Version Hide or show whether there is a missing module documentation version tag.
Show Missing Module Author Hide or show whether there is a missing module documentation author tag.
Show Missing Method Documentation Hide or show all documentation conflicts associated with methods.
Show Missing Method Documentation Description Hide or show missing method documentation conflicts.
Show Different Method Parameter Count Hide or show documentation conflicts where the number of comment parameters is different from the associated method.
Show Undocumented Method Parameters Hide or show documentation conflicts where there are missing parameters in the comment.
Show Incorrect Method Parameter Type Hide or show documentation conflicts where the type of comment parameters is different from the associated method.
Show Undocumented Method Return Hide or show documentation conflicts where the comment return is missing.
Show Incorrect Method Return Type Hide or show documentation conflicts where the type of comment return is different from the associated method.
Show Missing Method Pre-Conditions Hide or show documentation conflicts related to missing precondition documentation tags.
Show Missing Method Post-Conditions Hide or show documentation conflicts related to missing postcondition documentation tags.
Show Missing Property Documentation Hide or show all documentation conflicts associated with properties.
Show Missing Property Documentation Description Hide or show missing property documentation conflicts.
Show Different Property Parameter Count Hide or show documentation conflicts where the number of comment parameters is different from the associated property.
Show Undocumented Property Parameter Hide or show documentation conflicts where there are missing parameters in the comment.
Show Incorrect Property Parameter Type Hide or show documentation conflicts where the type of comment parameters is different from the associated property.
Show Undocumented Property Return Type Hide or show documentation conflicts where the comment return is missing.
Show Incorrect Property Return Type Hide or show documentation conflicts where the type of comment return is different from the associated property.
Show Missing Property Pre-Conditions Hide or show documentation conflicts related to missing precondition documentation tags.
Show Missing Property Post-Conditions Hide or show documentation conflicts related to missing postcondition documentation tags.
Show Missing Initialization Comments Hide or show documenation conflicts related to missing initialization comments.
Show Missing Finalization Comments Hide or show documenation conflicts related to missing finalization comments.
Show the origin method of the Parser error Hide or show the source parser method of the errors, warnings and hints in the module explorer. These are shown in square brackets at the end of the message.
Show all unreferenced symbols If the parser provide this information, all unreferenced symbols local and private symbols in the code are show as hints.
Show performance counters in the statusbar of the module explorer Hide or show the performance counters for the various stages of the parsing process in the module explorer status bar. This is a debugging option.
Show performance counters in the documenation summary Hide or show the performance counters for the various stages of the parsing process in the documentation summary table. This is a debugging option.
Strict evaluation of constant expressions This options when enabled will try to evaluate constant expressions strictly according to the types provided. This may show errors when different types are combined in the expression, so you may need to switch this option off for you coding style.
Show missing VB/VBA exception warnings Hide of show warnings related to exception handling in Visual basic files. This is only of use if you use my Exception framework for VB/VBA. See the VB Parsing information below for more information on this framework.
Add Pre and Post Conditions to Comments Enables ot disable the creation of pre and post tags in method and property comments when the are created by the IDE.

The refresh interval is the interval in milliseconds from the last edit or cursor movement after which the module explorer is refreshed.

Special Tags

The special tag are tags which can be displayed in the documentation and module explorer. If you wish to create your own then add them to the list.

Note: there is another specialised tag @stopdocumentation which if found in the module header comment will stop the documentation of all further conflict information. Additionally, If it is found in the method or property comment no documentation conflict checking will be undertaken for that method or property.

There are 3 option for each tag the determine their behaviour in the system as follows:

Option Description
Show in Tree This means that any of these tags found will be displayed in the module browser under a new heading based on Tag Name.
Auto Expand This means that this branch of the module explorer is always expand to display the item underneath.
Show in Doc This means that this tag will be output to the documentation.

Module Explorer

These options allow you to configure the module browse to your liking. You can change the font name and size and determine the colours and styles of the syntax higlighted treeview. Note: Not all the elements in the list are used by the parser for the treeview.

Additionally, the syntax highlighter settings here are used in the documentation, including the tree background colour.

Code Browsing

This option allows you to change the behaviour of the browser and editor interaction by specifying the position of the code and cursor when a node in the treeview is selected.

Exclude Doc Files

This is a simple list of path/filename patterns which should they exist in the files path and /or name (in both browsing and documenting) will cause Browse and Doc It not to display documentation conflicts should there be any found. This is useful for libraries of other peoples code you don’t wish to document. The pattern match use only a single character asterisk (*) to match one or more characters similar to DOS filename wildcards.

Method Descriptions

This is a list of pattens which are checked against method names and if the pattern matches, the description is automatically inserted for the method comment with the cursor being placed at the cursor marker position (a pipe sign).

Menu Shortcuts

Here you can modify the keyboard shortcuts for the Browse and Doc It menu items.

Module Extensions

This page of the options allows you to configure which modules file extensions are associated with the parsers and displayed in the module explorer.

Pascal Doc Comment Format

Browse and Doc It comments must start and end with the following character sequences respectively for the following code types:

Code Type Comment
Object Pascal
(** Comment text... **)

or

{: Comment text... }

or

//: Comment text...
Backus-Naur
/** Comment text... **/
Visual Basic All comment lines must start with

': Comment text...

As you can see these are extensions of the standard block comment in a similar manner to that used by JavaDoc. I’ll admit that the idea for this came from using Java and JavaDoc so alot of the idea here are very similar.

Tags in Browse and Doc It are like those is JavaDoc but are in 3 categories. The first category are special tags that are summaries in groups – these have previosuly been described in the Options section above.

The second type of tag contains only the one tag in the following form: {@link HRef Label} where label is optional. The tag can occur any where within the document comment and provides a hyper link cross reference mechanism.

The third type of tags are any single word starting with the @ character. These are just listed in the order that are found.

The documentation can support HTML tags which are passed through to the HTML documentation.

Parsers

Browse and Doc Now supports parsers for the following code:

  • Object Pascal;
  • Borland/CodeGear DFM files (text only);
  • Backus-Naur Grammar;
  • XML;
  • Eidolon MAP Files;
  • Eidolon Schematic Diagram Files;
  • INI Files.

A number of the new parser (Backus-Naur and Eidolon MAP Files) have had IDE highlighter written for them as they do not exist in the IDE. Unfortunately, due to a bug (I believe) in the RAD Studio 2009 IDE I haven’t been able to code the automatic creation of a Editor Options for these highlighter so that they are simple just there for you if you open these types of files. In order for you to use these highlighters, you will need to manually create a new editor option set for code types with the appropriate extensions and assign the new highlighter to this set of options.

You will find Backus-Naur grammar files (*.bnf) under the \Documenation of the source files which describe the grammar capabilities of these parsers.

Object Pascal

This highlighter is hooked to the file extensions pas, dpr and dpk.

This parser has been updated to include most of the new language features from Delphi 2009 including how ever methods in records, generics and anonymous methods and attributes.

Borland/CodeGear DFM Files (text only)

This highlighter is hooked to the file extension dfm. Note: this parser will only work with the text versions of the DFM files, you will need to convert older binary files to text if you with to browse the DFM files.

Backus-Naur

This highlighter is hooked to the file extension bnf.

I’ve constructed this grammar from information on WikiPedia. I deliberately chose to put the rule names in html tag style element as this made the parsing easier. To understand the grammar required to write more Backus-Naur grammars please refer to the Backus-Naour Grammer.bnf file included in the source files.

This parser supports 2 additional tags in the module header as follows:

Tag Description
@usesemicolon By default the rules in this parser need to end with a line break. However there are times when rule could do with being broken over separate lines (especially if they are compilcated rules). In this case, this tag (with no extra information) will terminate the rules with a semi-colon
@goal If your rules don't start with the rule <Goal>, then you can tell the parser to start at another named tag by using this tag followed by the name of the starting rule.

XML

This highlighter is hooked to the file extensions xml, xsd, html, htm and dtd.

Eidolon MAP Files

This highlighter is hooked to the file extension map.

This is a parser for the D’Sparil, Korax and Eidolon planning tool kits. This will not be useful until Eidolon is code.

Downloads

The current build of Browse and Doc It supports RAD Studio XE through XE 10.2 Tokyo and can be downloaded from the following link: Browse And Doc It 1.1 for RAD Studio XE to XE 10.2 Tokyo.