"Seegrid will be due for a migration to confluence on the 1st of August. Any update on or after the 1st of August will NOT be migrated"

Documenting your model or application schema

Contents

Related pages



Introduction

FullMoon generates API documentation for GML Application Schema (GAS) models. (See SchemaFormalization for more information about UML models of GML Application Schemas).

It is similar to API documentation tools that exist for modern programming languages (like Javadoc for Java).

It takes an input in the form of an XML document and generates a set of linked HTML pages as output. The input is an XMI (XML Metadata Interchange) representation of a GML Application Schema UML model.

Note: Currently this tool ONLY supports XMI models generated by the Enterprise Architect UML modeling tool (In particular the export of model packages as XMI Version 1.3). Future releases may support other UML IDE's and associated XMI artefacts.

Documenting your model

(For Enterprise Architect models only).

It is simple to add documentation to your UML model. Simply open the model you wish to document using Enterprise Architect and add notes (or comments) to each of the model elements. It is always a good idea to write them as you go so as not to end up with a huge documentation task after modelling is complete.

While it's not strictly necessary to add notes to every model element it is good practice to do so and it makes the auto-generated documentation far more readable and complete from a user-perpective.

Just what do we mean by "model element" ? The following UML class diagram elements should have notes/comments associated with them:

(Note: We assume here that they exist within, or are themselves, a Package with the stereotype «Application Schema»)

  • Packages (including «Application Schema» and «Leaf»stereotypes)
  • Classes
  • Class attributes
  • Class associations (seperate notes for Source roles and Target roles, when they exist)
  • Class diagrams (Yep - the diagrams are exported to the documentation pages and notes about them can be very useful)

Where do you find the notes fields for each of these elements? Mostly the "Properties" dialog box (right-click on model element and select "Properties") will bring up a dialog box with a "Notes" field.

For instance right click on a class (from within a diagram OR the Project Browser view) to show the Properties of a class. You should see something like this:

SampleClassProperties.jpg

For class attributes, select the "Detail" tab of the dialog box, click the "Attributes" button and select a single attribute from the list. You should see something like this:

SampleAttributeProperties.jpg

For a class associations (e.g. Target role), select the "Link" tab of the dialog box, double-click the appropriate association to open the association Properties dialog box, select the "Target role" tab. You should see something like this:

SampleTargetRoleProperties.jpg

Be aware that only simple text format is supported in the notes fields. Try to write your notes in a readable way with appropriate line breaks, punctuation etc, and leave blank lines between paragraphs.

Downloading the tool

The source code and binary disribution of the tool will soon be available for public use.

Running the tool

  • TODO: add content

What does the documentation look like ?

An example of the generated documentation overview page looks like this:

SampleGASDocPage1.jpg

An example of the generated package overview page looks like this:

SampleGASDocPage2.jpg

FAQ

  • TODO: add content

Summary

  • TODO: add content

This page is a work in progress.

I will endevour to update the contents over the next week (starting 30th April 2007)

Nick Ardlie.
Topic attachments
I Attachment Action Size Date Who Comment
SampleAttributeProperties.jpgjpg SampleAttributeProperties.jpg manage 43.0 K 08 May 2007 - 10:36 NickArdlie Sample Attribute Properties Image
SampleClassProperties.jpgjpg SampleClassProperties.jpg manage 55.9 K 08 May 2007 - 10:35 NickArdlie Sample Class Properties Image
SampleGASDocPage1.jpgjpg SampleGASDocPage1.jpg manage 155.9 K 02 May 2007 - 13:35 NickArdlie Sample GASDoc Page1
SampleGASDocPage2.jpgjpg SampleGASDocPage2.jpg manage 107.9 K 02 May 2007 - 13:35 NickArdlie Sample GASDoc Page2
SampleTargetRoleProperties.jpgjpg SampleTargetRoleProperties.jpg manage 39.9 K 08 May 2007 - 10:36 NickArdlie Sample Target Role Properties Image
Topic revision: r8 - 15 Oct 2010, UnknownUser
 

Current license: All material on this collaboration platform is licensed under a Creative Commons Attribution 3.0 Australia Licence (CC BY 3.0).