Delphi Clinic C++Builder Gate Training & Consultancy Delphi Notes Weblog Dr.Bob's Webshop
Dr.Bob's Delphi Notes Dr.Bob's Delphi Clinics Dr.Bob's Delphi Courseware Manuals
 Dr.Bob Examines... #100
See Also: Dr.Bob's Delphi Papers and Columns

Generating Documentation (using Together)
Delphi 2007 includes a full blown version of Together. At first sight, you may think this affects ECO (Enterprise Core Objects) for .NET developers only, but that’s not the case: Together integration can be found all over the place, including the professional editions of Delphi, as well as Win32 projects! The main part of the Together modelling support consists of the ability to draw and print UML diagrams. CodeGear RAD Studio supports UML Class Diagrams, Use Case Diagrams, Sequence Diagrams, Collaboration Diagrams, Statechart Diagrams, Activity Diagrams, Component Diagrams, and Deployment Diagrams.

Class Diagrams
The UML Class Diagrams are the most powerful in CodeGear RAD Studio, since they can be translated into source code (and vice versa).This means that we can design a Class Diagram that generates Delphi source code, or we can open an existing Delphi project or unit and let the Together designer draw the UML Class Diagrams for it.

LiveSource Class Diagrams
Delphi offers integration between the code editor and the Together UML designer.Using this Together UML designer, we can view UML schemas and diagrams of our source code.And not just view, but also alter the model, which is then reflected back into our source code.A two-way technology, called LiveSource Class Diagrams, which can be very helpful in getting more insights on complex units and visually extend class diagrams.
To demonstrate this feature, start a new Delphi application – VCL, VCL for .NET or even an ASP.NET or a Console application.For the example here, I’ll start with a Win32 VCL application called TogetherDemo with one form in MainForm.pas (named FrmDemo).Note the Project Manager, which shows the project as well as the units that are explicitly added to the project:

Note that the Project tree contains only the unit MainForm.pas. The Delphi project source file contains the following code:

  program TogetherDemo;
  uses
    Forms,
    MainForm in 'MainForm.pas' {FrmDemo};

  {$R *.res}

  begin
    Application.Initialize;
    Application.MainFormOnTaskbar := True;
    Application.CreateForm(TForm1, Form1);
    Application.Run;
  end.
The key point here is the in keyword, specified for the MainForm unit.As soon as a unit is explicitly added to the project, the keyword in is used, and the unit can be seen back in the Project Manager.
Why is this important, you may ask? Well, because the Together designer will only process files that are explicitly part of the project group, as outlined above.
In order to enable the LiveSource Class Diagram, we simply have to click on the Model View tab of the Project Manager. This will result in the following dialog, asking us if we should add modeling support now.
If you click on Yes, then you need to wait a few seconds, after which the Delphi IDE will show you the Model View with a number of new nodes, as shown in the following dialog.

The MainForm node both contain a little grey rectangle, which means it’s associated with a design diagram. If you double-click on the MainForm item you’ll get a diagram for the MainForm unit.
This diagram only consists of one item, the TFrmDemo class. Apart from classes, the Tool Palette shows the icons for the other UML elements we can add to the Class Diagram. If we right-click on the class diagram design surface, we can add a number of new elements (or nodes) to the diagram, namely: class, interface, association class, structure, enumeration, delegate, delegate as function, namespace, object, constraint and a comment note.
An UML class is equivalent to a Delphi class, while an UML Interface is similar to a Delphi interface. An UML Association Class is a class complete with a diamond icon and the ability to connect one or more other UML Classes, when representing a so-called n-ary association.
An association between two classes can be designed using the Association element from the Tools Palette.For an n-ary association, we first need to create an UML Association Class, and then connect the other classes using an Association End element, going from the diamond to each of the classes that are associated as well.
An UML Structure corresponds to a Delphi record, and an UML Enumeration is similar to a Delphi enumeration.
An UML Delegate corresponds to a Delphi “procedure of object”, in other words the method of a class.There can also be an UML Delegate as Function, which of course corresponds to a Delphi “function of object”.
An UML Namespace corresponds to a Delphi unit, with the name of the current unit as prefix.So if we add a new UML Namespace with the name “Info”, the corresponding Delphi unit will get the name MainForm.Info.This offers the ability to include more than one unit in the same diagram, although we only see a “summary” of the namespace contents, and not the actual full diagram itself.A diagram corresponds to a single unit (or namespace).
An UML Object is only a UML element, without a Delphi source code representation.An UML Constraint allows us to write OCL or Text description to accompany an association between two classes.And finally a Note can be used to add a description to the diagram, although the note does not end up in the documentation itself.

Together Document Generation
Speaking of documentation, apart from the UML diagrams we can also use the documentation generation functionality of the Together engine.Before we blindly generate some documentation, first configure the options using the Tools | Options dialog: If we scroll down in the Generate Documentation section of the options dialog, we get some Navigation options, which has the Generate Use option disabled.This can be a useful option, so I always enable it: We can now open a UML Class Diagram, right-click on the class diagram designer again (or right-click in the corresponding node in the Model View tree), and select the Generate Documentation option which will provide us with a dialog in which we can specify the output folder, the scope (entire project, current namespace, current diagram, etc), and the things you want to include. If the directory doesn’t exist, it will be created (otherwise previous contents will be deleted first), and when the documentation generation is done, it will automatically start the browser (as specified in the Launch HTML browser option of the Generate Documentation dialog).Until that time, a number of progress dialogs are shown.
The result is a directory with HTML files, images a stylesheet and a Java navigation.jar file to enable navigation through the documentation.Although quite empty at this time, especially for my demo project, it does show all classes, members, as well as the class hierarchy.

Documentation Elements
Documentation is only generated based on UML Class Diagrams and the documentation comments in the source code.The UML Class Diagrams are presented as clickable images, where we can select the Namespaces (units), Classes, Interfaces, Structs, Enumerations and their contents (fields, properties, methods, events, etc.).
Using the UML Class Diagram we can set properties of the diagram elements that will be translated into documentation comments.
A UML Class, Interface, Structure or Enumeration element has a number of documentation properties that can be configured using the Object Inspector, including Alias, Author, Since, and Version.The fields, methods and events also have their own Alias, Author and Since properties (but not the Version).
The Alias can be used to use a different name in the UML Class Diagram compared to the actual source code.The Author can be a helpful piece of information to contact the actual developer responsible for a section of code (the implementation of a method or event), and Since can be used for example to define the first (or last) date the particular element was modified.
The following is the resulting source code for the TLogonForm with the Alias, Author, Since and Version property given a value:

  type
    ///<alias>Login Form</alias>
    ///  <author>Bob Swart</author>
    ///  <since>1964</since>
    ///  <version>1.42</version>
    TLogonForm = class(TForm)
      ...
    end;
As you can see, the documentation comments appear just before the actual element itself, in this case the TLogonForm.Note that the Alias is the name which is displayed in the UML Class Diagram, and has no effect on the actual source code.
Setting the Alias, Author and Since properties of Class elements should have the same effect in the source code (but only if the DFM file can be shown – i.e.if all third-party components are installed and present).

Additional Documentation Elements?
Having only Alias, Author, Since, Version properties available (apart from source code specific properties like Sealed, Persistent, and Abstract) doesn’t really offer a lot to actually document a class, property or method.
Fortunately, it’s possible to add your own custom documentation comments, using the same syntax that was used before.
Some useful examples can be as follows (each on a single line only):

  /// <Description>This is one line description</Description>
  /// <Notes>This is one line with some notes</Notes>
The <Description> element even ends up in the class, property and method summary space. The obvious question would be how to get multiple lines of description or notes.For that, we only have to repeat the <description> or <notes> element with additional lines of content.The Together documentation engine will just put the contents together (in the order as specified in the source code):
  /// <description>This is the first line of the description</description>
  /// <description>This is the second line of the description</description>
  /// <description>This is the third line of the description</description>
  /// <description>This is the fourth line of the description</description>
The browser will automatically do the wrapping, so each line can be a real paragraph.

Together Documentation Live Template
Especially for the <Description> node, which is used by the documentation generation, but not normally editable from the model, we should have the ability to generate this without having to manually type a <Description>...</Description> entry.
We can design a special Together Documentation Live Template, which is defined as follows:

  <?xml version="1.0" encoding="utf-8" ?>
  <codetemplate xmlns="http://schemas.borland.com/Delphi/2005/codetemplates" version="1.0.0">
   <template name="dd" invoke="auto">
    <description>Together description</description>
    <author>Bob Swart</author>
    <point name="Element">
      <text>Description</text>
      <hint>description element</hint>
    </point>
    <point name="Message">
      <text>text</text>
      <hint>description text</hint>
    </point>
    <code language="Delphi" delimiter="|">
      <![CDATA[/// <|Element|>|Message|</|Element|>]]>
    </code>
    </template>
  </codetemplate>
Using this Live Template, we can type “dd” followed by a <tab> and then we can either change the node element (from Description to something else) and then <tab> again to write the actual description.Very helpful, and even easier to use than the diagram if there was a way to expose the description property.

Final Tips
Only units explicitly included in the project’s uses clause (using the in keyword) will be considered for the UML Class Diagrams as well as the QA Metrics and Audits and the Together Documentation. Place all comments and descriptions in the source code itself (and not in the diagrams), so you can always regenerate the model if needed. Make sure all UML Diagrams have a good layout (for printing) before generating the documentation. Include multi-line <Description> nodes using the Live Template defined above.The <Description> can be added for Unit, Class, Method, Property, etc.and will be a big part of the documentation itself.

Summary
In this article, I’ve covered the Together support – separate from ECO – in the CodeGear RAD Studio IDE.Specifically, I covered the Together’s way of generating documentation for the UML diagrams, which result in a standalone directory that you can zip and share with others when needed.
This article is an abstract from my 144-page book “Delphi 2007 for Win32 Development Essentials” which can be purchased for 20 Euro at Lulu.com in printed format (or for 15 Euro in electronical PDF).


This webpage © 2008-2010 by Bob Swart (aka Dr.Bob - www.drbob42.com).All Rights Reserved.