Documentation Insight 3 Sneak Preview #2

Written by Baoquan Zuo on . Posted in Documentation Insight

In previous preview, we experienced some brand new features in Documentation Insight 3, such as VS2012 presentation style, Inherited Documentation, Syntax Highlighter, Inheritance Hierarchy, etc. In this one, we will see two parts:

Part 1. Additional features about Documentation Generation.

1. FileName Policy

The new documentation generator supports three policies on file name generation:

* Signature

The generated file name will be basically same as the full name of a symbol.

e.g.  Spring.htm, Spring.IList(T).html

Special Rules:

a) For type parameters,  ‘<‘, ‘>’  will be replaced with ‘(‘ and ‘)’

b) If a method is not overloaded, its parameter type will not be added to the file name

c) For Operators, metadata name will be used.

* Unique Id

All file names will be random but unique id (like ‘a7ef980f.htm‘). All ids will be persisted into another file which will be loaded next time.

* Auto (Default)

By default,  the Signature policy will be used.  An unique id will be used and saved ONLY when a file name exceeds the max-path.

2. Lazy loading  for TableOfContents in Html

lazy-loading

Online demo:  http://www.devjetsoftware.com/demos/spring4d/

(P.S. you need to clear the browser cache if you have ever visited this url.)

3. Inherited documentation for property overrides

It will be very useful for component writers. for example:

PropertyOverridesSource

Generated doc:

PropertyOverrides

 

Part 2. New general features/improvements

External documentation repository

Documentation Insight 3 allows you to choose external documentation storage to keep source code clean. A fixed repository file (DocInsight.ini) will be placed in your project ROOT folder.

[Repository]
SourceDocsDir=SourceDocs

So no matter how you organized your projects in the directory, all source documentation files, which are organized by units, will be placed in the SourceDocs subfolder. (e.g. Spring.xml, Spring.Collections.xml)

A drawback is that the documentation will not be displayed in the built-in Help Insight feature. More details will be published in later documentation.

Documentation Inspector

* Automatically switch between Code Editor & Documentation Inspector when pressing the hotkey
* Auto focus and switch to design mode when shown

Documentation Explorer

* Document Member Summary

You will be able to document member summary just like enumerated members:

document-member-summary

* Sync with current project group

* Remember window state

* Improve Mouse wheel handling

Hotkeys
* Show Documentation Inspector (Ctrl+Shift+D)
* Show Documentation Explorer (Alt+Shift+N)
* Collapse documentation in the Code Editor (Alft+Shift+C)
* Expand documentation in the Code Editor (Alft+Shift+E)

Update options:
* Enable/Disable Automatic check for updates
* Update channel (Debug or Release)

New Generation Compiler

* Conditional defines (Initial conditional defines)
* Conditional expressions (e.g. {$IF defined(POSIX) and not defined(IOS)})
* Include file  (e.g. {$I jedi.inc})
* Search Paths
* Bug fixes

 

We will announce our Beta news on our Google Plus community, you are welcome to follow us on G+

https://plus.google.com/communities/113012729454639868890

Documentation Insight 3 Sneak Preview #1

Written by Baoquan Zuo on . Posted in Documentation Insight

Documentation Insight 3 is a brand new version. It includes significant new features and improvements. Since it is close to announce first Beta version of Documentation Insight (DI) 3, let’s take a look at some parts of DI3 in this Sneak Preview series.

In this preview, you will experience the new Documentation Generator.

1. VS 2012 Presentation style

Compared to previous classic presentation, the new VS2012 (like) presentation style in DI 3 is more clean and elegant.

snapshot1

2. Group by Projects

You may organize the units by Projects. The documentation in project source will be showed in the corresponding topic.

3. Inheritance Hierarchy

snapshot2

For class and interface types, all base types and derived types are showed in the inheritance hierarchy.

4. Syntax Highlighter

Both the syntax prototype and code examples will be highlighted.

snapshot9

5. Inherited Members & Filters

snapshot3

 

All inherited members will be displayed in the member list. You may also filter the members by clicking the right check boxes (inherited /protected)

6. Information on Overloads/Overridden/Implements

There will be additional information if a member has overloads, or overridden a member, or what methods of interfaces was implemented by this method.

snapshot5

 

snapshot6

 

Method resolution clause is also supported.

7. Inherited Docs

The documentation generator will try to reveal documentation from overridden members or implemented members. Say you documented an interface IList<T> and TList<T> implements the interface, then All members of TList<T> will inherit documentation from the interface IList<T> if available.

8. Improvements about hyperlinks in code

We spent several months to reveal Delphi grammar and built our own compiler front-end from scratch. Therefore, it is possible to resolve symbols in code.

snapshot7

9. Default documentation

For some code elements, we may choose default (friendly) documentation. e.g. For constructor/destructor/class constructor/class destructor/class operators/resource strings. Say for an instance constructor, its default documentation may looks like:

Initializes a new instance of  the TFoo class.

10. More XMLDoc tags

If you want exclude an member from your final documentation file,  you may apply self closed <exclude /> tag against the API. If a property should be taken as an event, you may apply <event /> tag to it. (e.g. property OnChanged: Event<TNotifyEvent>;)

 

Online Demo:

http://www.devjetsoftware.com/demos/spring4d/

 

Known issues in the demo:

* Some keywords will not be highlighted.

* The default topic was not synced in the TableOfContents.

 

Future work on Documentation Generator:

* Supports Overloads

* Resolve RTL/VCL symbols and produce hyperlinks to online RAD Studio Library DocWiki. (Or maybe even the MSHelp2 links)

* Consider PDF/Html Search

ANN: Documentation Insight Maintenance update (Supports XE4 and 2006)

Written by Baoquan Zuo on . Posted in Documentation Insight, News

Documentation Insight is a professional source code documentation solution for Delphi. This maintenance update includes:

V2.8.4.19

+ Support RAD Studio XE4
+ Support Delphi 2006 (with Update 2)
# Missing file extension when clicking “New Project” and modified the default file name
# Possible missing documentation of exceptions

http://www.devjetsoftware.com/downloads/

Documentation Insight V2.7.10.18 Released

Written by Baoquan Zuo on . Posted in Documentation Insight, News

This minor update includes several important bug fixes and enhancements:

V2.7.10.18 2012-10-18
[Common]
+ Readded the Reload tool button (Shortcut: F5)
* adjust the min-height of section content in design mode
* Improve style of image (no-border, auto-scale)
* improve definition table (trim white spaces of term, support rich text in description)
* Improve the usability of Cut/Delete a Table/Note/Code Snippet
# AV error raised when clicking Hyperlink in some cases
# AV error raised in DocExplorer when selecting an entity removed in source file
# Interface not supported error raised in DocExplorer
# Unspecified error raised when pressing F5 in Design Mode
# Image won’t be saved when the src attribute contains spaces (encoded to %20)
# Missing documentation when inserting an image as a standalone paragraph
# Missing documentation when a section tag contains only one code reference without display name
# Missing Icon when inserting a code snippet

[Documentation Generation]
+ Support local image and other file types specified in the href/src attributes of <a>, <img> elements
+ Support html elements <a>, <img> for H&M
# No application icon in Taskbar
# failed when current work directory is not the same as the application
# The results form doesn’t hide even specified “silent” option

Documentation Insight V2.6.9.5 supports Help & Manual and XE3

Written by Baoquan Zuo on . Posted in Documentation Insight

We are very pleased to announce that Documentation Insight now supports Help & Manual and RAD Studio XE3.

Help & Manual is a well-known help authoring software and we write general help manual by this stuff. Documentation Insight can extract documentation from your source code and generate H&M files so that you may merge it into your own H&M project. Then you can customize the template in H&M and publish them together to produce uniform help files and deliver to your customers. (H&M also supports various formatting e.g. Web page, CHM, PDF, RTF, E-Books.)

Just check Help & Manual in the Publish page:

The following sample demonstrates the generated H&M files for Spring4D:

Applying a H&M skin and publish to a CHM file like this:

Important Note: Once the H&M project file was generated, Documentation Insight only updates the project information (Title, Author, Copyright) while all API documentation topics in the H&M project will be overwritten without any confirmation. You should not edit the generated topics in H&M otherwise your changes will be lost.

This update also includes the following improvements and important bug fixes:

V2.6.9.5   2012-09-05
New features:
– Support Help & Manual (Tested in H&M 5/6)
– Support XE3

Improvements:
– Add “Show Private Members” in DocGen Options
– Install for all users
– Place holder for Bad Xml Documentation
– Add logs in the DocGen results

Bug Fixes:
– Clicking an index entry in HTML results in two same pages on both sides
– Some broken code references
– Duplicated Implicit/Explicit class operators Signature
– Duplicated Signature (class constructor/destructor with normal)
– Error dialog shown when fatal parser error occurred

To download this version, please visit the Downloads page.

Documentation Insight Update (V2.6.8.20)

Written by Baoquan Zuo on . Posted in Documentation Insight

This version V2.6.8.20 is a minor update including the following changes:

Improvements:
– Support variables in DocGen html templates
<%Title%>,<%Author%>,<%Summary%>,<%Comment%>,<%Copyright%>,<%TopicTitle%>
– Optimized Performance for Documentation Explorer
– Show Private Members in Documentation Explorer/Hyperlink window
– Show Syntax definition in Documentation Explorer
– Improve the DocGen result form
– Detecting IDE exists in the installer
– Automatic check updates

Bug-fixes:
– Support Delphi 7 (Build 8.1)
– DocInsight.exe taskbar issue
– The Edit box in the html index page lost focus after loaded keywords
– Missing Generic characters (<>) in Html Indexes

Downloads:

http://www.devjetsoftware.com/downloads/

ANN: Documentation Insight Enterprise Beta (Including Documentation Generator)

Written by Baoquan Zuo on . Posted in Documentation Insight

We are so pleased to announce the first beta of Documentation Insight Enterprise version. This version includes all features in V2 Professional plus a tool set of Documentation Generator.

Change log:

V2.6.8.15 (Beta)
– Documentation Project wizard
– Generate Web page files which includes html files, table of contents and index page with a search box.
– Generate CHM file
– Generate Microsoft Help 2.0 file (Requires Microsoft Help 2.0 Compiler distributed with VS2003-2008)
– Documentation Generator Command line tool (DocInsight.exe)
– Register tool to integrate a Microsoft Help 2.0 file into RAD Studio Documentation (reghelp.exe)
# Fixed a parsing issue (type of identifier)

It is strongly recommended that you see the following Tutorial topic to know all these new stuff:

How to Generate Delphi Code Documentation Files in Documentation Insight


All prepaid customers will receive upgrade license in hours.

Special Discount in August (Before August 31th, 2012)

* Buy Documentation Insight Enterprise now you will save 20%

* If you have purchased Documentation Insight V2 Professional and would like to upgrade to Enterprise version, we also offer a special discount for you (20% off)

Buy Now

It should be noticed that this is still a beta version. If you have any problems, please write to us:  support@devjetsoftware.com

Known Issues:
* Delphi 7 will be supported soon (Highest priority)
* DocInsight.exe might not be shown when you run it and then click the taskbar icon twice.
* The topic web pages can’t be scroll in iPad+ Safari
* Generic types which contains more than one type parameters can’t be automatically linked in syntax definition
* Some Web browsers (Chrome) has restricts for local web pages which make index page and auto scroll feature useless

[Tutorial] How to Generate Delphi Code Documentation Files in Documentation Insight

Written by Baoquan Zuo on . Posted in Documentation Insight

Documentation Insight Enterprise version helps you produce rich documentation files with only a few steps. Here we go:

1. Open an existing project or a project group in RAD Studio

2. Click the menu DocumentationGenerate Documentation…

Tip: Documentation Insight will find the corresponding documentation project (.diproj file) in the same location of the current project (or group). A default project will be created if not found. You may also click the New Project to create a new empty documentation project or use Open Project to open an existing project.

3. We will see some basic information in the first step:

4. By default, all current source code projects in the IDE will be added into the documentation project, you may add or remove any project.

5. We can customize the header and footer template in the third step. If we would like to generate documentation for code elements in the implementation section, just check the first option.

Note: The templates must be valid. You may use the following variables: <%TopicTitle%>, <%Title%>,<%Author%>,<%Summary%>,<%Comment%>,<%Copyright%>

6. Publish options
In the last step, we may choose the output types and their corresponding location. The locations are relative to current documentation project.


Note: To generate a Microsoft Help V2.x (Single HxS file) file, you require Microsoft Help 2 Compiler which is distributed with Visual Studio 2003-2008.
Finally, just click the Generate button, Documentation Generator will compile the source projects and produce various documentation files for you.

Tick, tick, tick… It Succeeded!

 


Here lists all results in the generation process.
You may click the hyperlinks to preview the generated artifacts:

* Web pages


Default page

The Index tab
We use a lightweight local server (Help & Manual H2 Go) to preview html files as some web browsers have restrictions for local web pages.

Online help: http://www.spring4d.org/help/

CHM file

Microsoft Help 2 file
When you click the hyperlink of MSHelp2 file (Single .HxS file), the file will be automatically registered and Documentation Insight will use Microsoft Documentation Explorer (dexplore.exe) to browse the help file.

The help file will be automatically integrated into your local RAD Studio Documentation (2005-XE2).

Help & Manual


OK. Now you may have a try. If you have any questions or problems, please write to us: support@devjetsoftware.com