Home
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 XE4;
- Embarcadero RAD Studio XE5;
- Embarcadero RAD Studio XE6;
- Embarcadero RAD Studio XE7;
- Embarcadero RAD Studio XE8;
- Embarcadero RAD Studio 10 Seattle;
- Embarcadero RAD Studio 10.1 Berlin;
- Embarcadero RAD Studio 10.2 Tokyo;
- Embarcadero RAD Studio 10.3 Rio;
- Embarcadero RAD Studio 10.4 Sydney;
- Embarcadero RAD Studio 11.0 Alexandria.
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).
- Fixed issues with backwards compatibility from RS 11.0 backwards due to new
TFramepropertyPixlesPerInch.
- Updated for RAD Studio 11.0;
- Browse and Doc It will not auto-update the date and version number in the module's header comment when the file is saved;
- Added the ability to spell check resource string, constants and comments (including literals in the DFM files);
- Numerous bug fixes (see the GitHub commit history).
- Module Metrics - The following metrics are available: Long Method, Long Parameter List, Long Variable List, Nested IF Depot, Method Cyclometric Complexity and Method Toxicity. These can appear in the Module Explorer but are also available in an Editor Sub View for each module or an Editor View for the whole project;
- Module Checks - The following checks are available: Hard-Coded Integers, Hard Coded Numbers, Hard-Coded Strings, Unsorted Method, Use of WITH Statement, Use of GOTO statement, Empty EXCEPT Block, Empty FINALLY Block, Exception Eating, Empty THEN Block, Empty ELSE Block, Empty CASE Block, Empty FOR Block, Empty WHILE Block, Empty REPEAT Block, Empty BEGIN END Block, Empty Initialization Block, Empty Finalization Block, Empty Method and Missing CONST in Method Parameter. These can appear in the Module Explorer but are also available in an Editor Sub View for each module or an Editor View for the whole project;
- Colour support for Special Tags - These can now be coloured to make them stand out in the Module Explorer;
- Unicode Support - Fixed an issue with converting the editor code to Unicode;
- Some 10.2/10.3 theming support has been added however the IDE.
- Updated the Special Tags to allow each to be configured as a fixed font and and have optional Syntax highlighting - these are reflected in the Module Explorer and hint windows;
- Update the Errors, warnings, Hints and Documentation Conflicts to be optionally Syntax highlighted.
- Update the Object Pascal parser to handle Generics, Anonymous Methods and Attributes;
- Added the ability to filter the Module Explorer (just focus it and type a regular expression);
- Added the ability to customise the plug-ins short-cuts;
- Added the ability to customise the file extensions which are associated with the various parsers (BNF, DFM, OP, XML and INI).
Browse And Doc It is design to be loaded as a DLL expert. You can use GExperts' (https://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
regeditand press <Enter>; - Browse to the key
HKCU\Software\Embarcadero\BDS\22.0</code> (change the path number for your IDE); - If there is no key called
Expertsthen you will need to create one; - Under
Expertscreate a new string as follows:-
Key=BrowseAndDocItRS110; -
Value=Drive:\Path\BrowseAndDocItRS110.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....
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.
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:
-
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.
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.
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.
This options inserts a block pascal comment. This is useful for module comments where you wish to describe 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.
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.
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.
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 Object Pascal code can be used to generate DUnit tests.
This dialogue 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 inserted 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.
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.
The options for Browse and Doc It has grown since Pascal Doc and are now broken down into the following sections:
There are eight pages of options for Browse and Doc It as follows:
The general option for Browse and Doc It are as follows (and are now categories):
- 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 Child Count in Titles - This option show the number of child nodes after the node title.
- Follow the Editor Cursor - This option will make the module explorer automatically select the relative element associated with where the cursor is in the editor.
- Show Documentation Issues Totals in the Code Editor - This options displays a floating summary of issues in your code in either the top right or bottom right corner of the editor.
- Automatically update the module date on saving - This option will automatically update the date in the @Date tag of a module summary comment.
- Automatically update the module version on saving - This option will automatically update the version in the @Version tag of a module summary comments.
- Show Module Errors - Hides or shows the errors found in the code currently being browsed.
- Automatically Expand Errors - .
- Syntax Highlight Module Errors - Enables or disables syntax highlighting of the module errors.
- Show Error Icons in the Code Error - .
- Show Error Messages in the Code Editor - .
- Show IDE Errors in the Module Explorer - .
- Show Module Warnings - Hides or shows the warnings found in the code currently being browsed.
- Automatically Expand Warnings - .
- Syntax Highlight Module Warnings - Enables or disables syntax highlighting of the module warnings.
- Show Warning Icons in the Code Error - .
- Show Warning Messages in the Code Editor - .
- Show Module Hints - Hides or shows the hints found in the code currently being browsed.
- Automatically Expand Hints - .
- Syntax Highlight Module Hints - Enables or disables syntax highlighting of the module hints.
- Show Hint Icons in the Code Error - .
- Show Hint Messages in the Code Editor - .
- Show Documentation Conflicts - Hides or shows the documentation conflicts found in the code currently being browsed.
- Automatically Expand Documentation Conflicts - .
- Syntax Highlight Documentation Conflicts - Enables or disables syntax highlighting of the module document conflicts.
- Show Documentation Conflict Icons in the Code Error - .
- Show Documentation Conflict Messages in the Code Editor - .
- Show Module Checks - Hides or shows the module checks found in the code currently being browsed.
- Automatically Expand Module Checks - .
- Syntax Highlight Module Checks - Enables or disables syntax highlighting of the module checks.
- Show MOdule Checks Icons in the Code Error - .
- Show Module Checks Messages in the Code Editor - .
- Show Module Metrics - Hides or shows the module metrics found in the code currently being browsed.
- Automatically Expand Module Metrics - .
- Syntax Highlight Module Metrics - Enables or disables syntax highlighting of the module checks.
- Show Module Metrics Icons in the Code Error - .
- Show Module Metrics Messages in the Code Editor - .
- Show Module Spelling Mistakes - Hides or shows the module spelling mistakes found in the code currently being browsed.
- Automatically Expand Module Spelling Mistakes - .
- Syntax Highlight Module Spelling Mistakes - Enables or disables syntax highlighting of the module spelling mistakes.
- Automatically Hide Spelling Mistakes with no issues in the Editor Views
- Show Module Spelling Mistakes Icons in the Code Error - .
- Show Module Spelling Mistakes Messages in the Code Editor - .
- Spell check the main comment text - .
- Spell check @precon and @postcon tags in comments - .
- Spell check resource strings - .
- Spell check constants - .
- Spell check string literals - .
- Spell check DFM string literals - .
- Errors - .
- Warnings - .
- Hints - .
- Documentation Conflicts - .
- Code Checks - .
- Code Metrics - .
- Code Spelling Mistakes - .
- 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 documentation conflicts related to missing initialization comments.
- Show Missing Finalization Comments - Hide or show documentation 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 status bar 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 documentation 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.
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 options for each tag the determine their behaviour in the system as follows:
- Tree - This means that any of these tags found will be displayed in the module browser under a new heading based on Tag Name.
- Expand - This means that this branch of the module explorer is always expand to display the item underneath.
- Docs - This means that this tag will be output to the documentation.
- Fixed - This means that this tag will use a fixed font (see Module Explorer options) to render the tag information in the tree.
- Syntax - This means that this tag will use syntax highlighting (see Module Explorer options) to render the tag information in the tree.
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 highlighted 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.
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.
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.
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).
Here you can modify the keyboard shortcuts for the Browse and Doc It menu items.
This page of the options allows you to configure which modules file extensions are associated with the parsers and displayed in the module explorer.
Browse and Doc It comments must start and end with the following character sequences respectively for the following code types:
- 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 a lot of the ideas here are very similar.
Tags in Browse and Doc It are like those in JavaDoc but are in 3 categories. The first category are special tags that are summaries in groups - these have previously 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 the label is optional. The tag can occur anywhere within the document comment and provides a hyperlink cross-reference mechanism.
The third type of tags are any single word starting with the @ character. These are just listed in the order they are found.
The documentation can support HTML tags which are passed through to the HTML documentation.
Browse and Doc Now supports parsers for the following code:
- Object Pascal;
- Borland/CodeGear DFM files (text only);
- Backus-Naur Grammar;
- XML;
- 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 an Editor Options for these highlighters so that they are simply 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.
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 however methods in records, generics and anonymous methods and attributes.
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 wish to browse the DFM files.
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 the 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:
- @usesemicolon - By default, the rules in this parser need to end with a line break. However, there are times when rules could do with being broken over separate lines (especially if they are complicated 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.
This highlighter is hooked to the file extensions XML, XSD, HTML, HTM and DTD.