Documentation Insight makes it a lot easier to document your source code. It enables you explore source code library with live documentation and helps you produce rich API documentation files and integrate into RAD Studio Documentation.
Documentation Insight integrates into RAD Studio IDE as an add-in. The Documentation menu will appear in the IDE when you have installed it.
Once you open a Delphi source unit, Documentation Inspector will show visual documentation of the current source code element in the Code Editor in the Preview mode. It stays in sync with the Code Editor and will be reloaded when you switch units or move cursor in a source file.
At present, Documentation Insight recognizes XML Documentation, which starts with triple slashes (///) and consists of well formatted xml tags and text, in source code. Basically, There are several sections in API Documentation which serves different purposes:
| Summary | A short description on the code element |
| Syntax | Illustrates the type parameters, parameters, return/value type |
| Exceptions | Tells callers what exceptions may be raised |
| Remarks | Any additional information and further explaination |
| Examples | Demonstrates how to use the code |
| See Also | Code References or Other Resources |
All of them can be represented by corresponding xml tags, e.g. <summary>, <remarks>, <examples>. It is recommended that you read Delphi Documentation Guidelines which includes a detailed XML Documentation Reference.
Fortunately, we don’t need to care about the syntax in Documentation Insight. We can start documenting source code by switching to the Design mode.
Documentation Insight is so smart that it automatically retrieves all meta data such as parameter names from source code and produces proper layout to let us write documentation. For enumerated types, it even populates all members and allow us to document them in the same place:
The editor is both intuitive and powerful. We may use either the toolbar or shortcuts to enrich our documentation, including:
1. Mark any text as bold, italic, underline, strike-through or inline code.
2. Insert or Edit an Ordered List/Unordered list, Hyperlinks, Tables, Images, Notes and Code Snippets.
The Live Spelling feature will give us suggestions on any possible syntax errors in documentation.
We just need focus on writing documentation itself and we don’t have to pay any attention to xml tag syntax. Documentation Insight will generate well-formatted xml documentation and place it in source code.
Tip: Xml documentation can be folded in XE2 or higher, to make source code look clean. It is also possible to use REGION directive in Documentation Insight to fold xmldoc:
Documentation Insight also enhances the IDE to make the Help Insight feature support all xml tags and look more professional.
It should be also mentioned that Documentation Inspector will extract documentation from local RAD Studio documentation (if available) when you open a VCL unit.
Documentation Explorer, as its name says, allows you explore the opened source projects with live documentation without compiling them to static help files. It shows all namespaces, classes, interfaces, types and all members. You can document all source code in Documentation Explorer without switching between different units.
In last, let’s see two useful features:
Validate Documentation – Validates all xml documentation in your source code and it will tell you errors with file name, error reasons in the Messages view. You may double click an entry to locate to the source line to modify xmldoc manually.
Format Documentation – Makes your xml documentation look beautify by adding proper white spaces and line breaks.
OK. We have seen the most basic features in Documentation Insight, in the next tutorial, we will learn how to use Documentation Insight to produce web pages, CHM file, Microsoft Help 2 file and Help & Manual files from source code.
How to Generate Documentation from Delphi Source Code