From f602edc5873381755f5e43c9e09a0b2ab1a48a0a Mon Sep 17 00:00:00 2001
From: Diomidis Spinellis <dds@aueb.gr>
Date: Thu, 29 Nov 2007 13:02:58 +0000
Subject: [PATCH] Document new functionality.

---
 doc/cd-model.xml    |  4 +++
 doc/cd-note.xml     | 47 ++++++++++++++++++++++++++++
 doc/cd-opt-spec.xml | 46 +++++++++++++++++++++++++++
 doc/cd-opt.xml      | 55 +++++++++++++--------------------
 doc/ceg-shape.xml   | 75 +++++++++++++++++++++++++++++++++++++++++++++
 doc/index.xml       |  3 ++
 doc/note.java       | 26 ++++++++++++++++
 doc/shapes.java     | 67 ++++++++++++++++++++++++++++++++++++++++
 doc/ver.xml         |  7 ++++-
 doc/views.xml       |  1 -
 10 files changed, 296 insertions(+), 35 deletions(-)
 create mode 100644 doc/cd-note.xml
 create mode 100644 doc/cd-opt-spec.xml
 create mode 100644 doc/ceg-shape.xml
 create mode 100644 doc/note.java
 create mode 100644 doc/shapes.java

diff --git a/doc/cd-model.xml b/doc/cd-model.xml
index e02b08d..964dd7a 100644
--- a/doc/cd-model.xml
+++ b/doc/cd-model.xml
@@ -5,6 +5,10 @@ The UMLGraph class diagrams allows you to model
 <ul>
 <li>classes (specified as Java classes)
 </li>
+active classes, components, nodes, use cases,
+collaborations, and packages
+(specified as Java classes with an <code>@opt shape</code> tag)
+</li>
 <li>attributes (specified as Java class fields)
 </li>
 <li>operations (specified as Java class methods)
diff --git a/doc/cd-note.xml b/doc/cd-note.xml
new file mode 100644
index 0000000..b784126
--- /dev/null
+++ b/doc/cd-note.xml
@@ -0,0 +1,47 @@
+<?xml version="1.0" ?>
+<!-- $Id$ -->
+<notes>
+In UMLGraph you can easily add a note (comment) to an element,
+using the <code>@note</code> tag.
+The corresponding text will be split into lines, as specified in the note.
+Multiple tags can be used to add more notes to the same element.
+More complicated, (one to many) relationships can be established
+by creating an element with a note shape, setting its contents
+to its comment text through the <code>@opt commentname</code> tag,
+and associating it with other elements with the <code>@assoc</code>
+tag.
+<table>
+<tr><td>
+<fmtcode ext="java">
+/**
+ * @opt shape node
+ * @note Located in the
+ * machine room
+ * @note Sun Blade 6048
+ * @depend - - - MapLocation
+ * @depend - - - DataMine
+ */
+class Server{}
+
+/** @opt shape component */
+class MapLocation {}
+
+/** @opt shape component */
+class DataMine {}
+
+/**
+ * CPU-munching
+ * components that must
+ * run on this server
+ * @opt shape note
+ * @opt commentname
+ * @assoc - - - MapLocation
+ * @assoc - - - DataMine
+ */
+class munchComment {}
+</fmtcode>
+</td><td>
+<img src="note.gif" alt="UML note example" />
+</td></tr></table>
+
+</notes>
diff --git a/doc/cd-opt-spec.xml b/doc/cd-opt-spec.xml
new file mode 100644
index 0000000..32cea35
--- /dev/null
+++ b/doc/cd-opt-spec.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" ?>
+<!-- $Id$ -->
+<notes>
+Since the options are really a part of the generated graph you
+want in many cases to include them in the diagram specification.
+You can do that by adding <em>javadoc</em> <code>@opt</code> tags in front
+of a class named <code>UMLOptions</code>, as in the following example:
+<fmtcode ext="java">
+/**
+ * @opt horizontal
+ * @opt all
+ * @hidden
+ */
+class UMLOptions {}
+</fmtcode>
+<p>
+Similarly, you can also globally specify options for all the note elements.
+through a class named <code>UMLNoteOptions</code>, as in the following example:
+<fmtcode ext="java">
+/**
+ * @hidden
+ * @opt nodefontcolor "blue"
+ */
+class UMLNoteOptions{}
+</fmtcode>
+<p>
+
+You can also change the UMLGraph operation on a per-class basis by
+using <code>@opt</code> attributes on individual classes.
+In this case the <code>@opt</code> specification temporarily overrides
+the particular global setting for the class being processed.
+
+<p/>Finally, you can reset an option to its default value by prefixing it
+    with an exclamation mark. For example:
+<fmtcode ext="java">
+/**
+ * @opt !attributes
+ * @opt !nodefontsize
+ */
+class MyClass {}
+</fmtcode>
+
+will disable attribute listing for MyClass, and reset the node font size
+to its default value (10).
+</notes>
+
diff --git a/doc/cd-opt.xml b/doc/cd-opt.xml
index 1603995..ad92c4c 100644
--- a/doc/cd-opt.xml
+++ b/doc/cd-opt.xml
@@ -1,8 +1,12 @@
 <?xml version="1.0" ?>
 <!-- $Id$ -->
 <notes>
-A number of command-line options contol the operation of UMLGraph
-class diagram generator:
+A number of options contol the operation of UMLGraph
+class diagram generator.
+These can be specified on the command line, and most can also
+be specified within the diagram, affecting all or some elements.
+<p/>
+The following options are supported:
 <dl>
 <dt>-output</dt><dd>Specify the output file (default <code>graph.dot</code>).
 If the output directory is provided, -output can only specify a file name,
@@ -48,6 +52,9 @@ types.
 <code>-enumerations</code>
 <code>-enumconstants</code>
 </dd>
+<dt>-commentname</dt><dd>Name the element using the text in the javadoc
+comment, instead of the name of its class.
+</dd>
 <dt>-nodefillcolor</dt><dd>Specify the color to use to fill the shapes.
 </dd>
 <dt>-nodefontname</dt><dd>Specify the font name to use inside nodes.
@@ -90,6 +97,19 @@ names (used only when it package name is postfixed, see -postfixpackage).
 package name in the line after the class name, in order to reduce the
 width of class nodes.
 </dd>
+<dt>-shape</dt><dd>Specify the shape to use for the rendered element(s).
+The following UML shapes are available:
+<ul>
+<li>class (default)</li>
+<li>node</li>
+<li>component</li>
+<li>package</li>
+<li>collaboration</li>
+<li>usecase</li>
+<li>activeclass</li>
+</ul>
+</dd>
+
 <dt>-hide</dt><dd>Specify entities to hide from the graph.
 Matching is done using a non-anchored regular match.
 For instance, "<code>-hide (Big|\.)Widget</code>" would hide "<code>com.foo.widgets.Widget</code>" and
@@ -184,35 +204,4 @@ you can find a complete list in the
 Font names are passed directly to the dot graph generation back-end.
 In general the Postcript standard names Times, Helvetica, Courier, and
 Symbol are safe to use.
-<p />
-Since the options are really a part of the generated graph you
-want in many cases to include them in the diagram specification.
-You can do that by adding <em>javadoc</em> <code>@opt</code> tags in front
-of a class named <code>UMLOptions</code>, as in the following example:
-<fmtcode ext="java">
-/**
- * @opt horizontal
- * @opt all
- * @hidden
- */
-class UMLOptions {}
-</fmtcode>
-
-You can also change the UMLGraph operation on a per-class basis by
-using <code>@opt</code> attributes on individual classes.
-In this case the <code>@opt</code> specification temporarily overrides
-the particular global setting for the class being processed.
-
-<p/>Finally, you can reset an option to its default value by prefixing it
-    with an exclamation mark. For example:
-<fmtcode ext="java">
-/**
- * @opt !attributes
- * @opt !nodefontsize
- */
-class MyClass {}
-</fmtcode>
-
-will disable attribute listing for MyClass, and reset the node font size
-to its default value (10).
 </notes>
diff --git a/doc/ceg-shape.xml b/doc/ceg-shape.xml
new file mode 100644
index 0000000..d9c06e6
--- /dev/null
+++ b/doc/ceg-shape.xml
@@ -0,0 +1,75 @@
+<?xml version="1.0" ?>
+<!-- $Id$ -->
+<notes>
+<fmtcode ext="java">
+/**
+ * @hidden
+ * @opt nodefontcolor "blue"
+ */
+class UMLNoteOptions{}
+
+/**
+ * Structural Things
+ * @opt commentname
+ * @note Notes can
+ * be extended to
+ * span multiple lines
+ */
+class Structural{}
+
+/**
+ * spelling.java
+ * @opt shape component
+ * @opt commentname
+ * @note Component
+ */
+class Component extends Structural{}
+
+/** @opt shape node */
+class Node extends Structural{}
+
+/**
+ * Chain of
+ * responsibility
+ * @opt shape collaboration
+ * @opt commentname
+ * @note Collaboration
+ */
+class Collaboration extends Structural{}
+
+/**
+ * Place order
+ * @opt shape usecase
+ * @opt commentname
+ * @note Use Case
+ */
+class UseCase extends Structural{}
+
+/**
+ * Business rules
+ * @opt shape package
+ * @opt commentname
+ * @note Package
+ */
+class Package{}
+
+/**
+ * @opt all
+ * @note Class
+ */
+class Counter extends Structural {
+	static public int counter;
+	public int getCounter();
+}
+
+/**
+ * @opt shape activeclass
+ * @opt all
+ * @note Active Class
+ */
+class RunningCounter extends Counter{}
+
+</fmtcode>
+<p/>
+<img src="shapes.gif" alt="UML diagram showing the shapes supported by UMLGraph" />
+</notes>
diff --git a/doc/index.xml b/doc/index.xml
index 799150f..9823957 100644
--- a/doc/index.xml
+++ b/doc/index.xml
@@ -6,9 +6,12 @@
 <ch><ti>Class Diagrams</ti><fi>cd-intro</fi></ch>
 <ch><ti>Class Diagram Operations</ti><fi>cd-oper</fi></ch>
 <ch><ti>Class Modelling</ti><fi>cd-model</fi></ch>
+<ch><ti>Notes in Class Diagrams</ti><fi>cd-note</fi></ch>
 <ch><ti>Class Diagram Options</ti><fi>cd-opt</fi></ch>
+<ch><ti>Specifying class Diagram Options</ti><fi>cd-opt-spec</fi></ch>
 <ch><ti>Javadocs and UML class diagrams with UMLGraphDoc</ti><fi>cd-umldoc</fi></ch>
 <ch><ti>Class Diagram Views</ti><fi>views</fi></ch>
+<ch><ti>Class Diagram Example: Shapes</ti><fi>ceg-shape</fi></ch>
 <ch><ti>Class Diagram Example: Generalisation Relationships</ti><fi>ceg-gen</fi></ch>
 <ch><ti>Class Diagram Example: Advanced Relationships</ti><fi>ceg-adv</fi></ch>
 <ch><ti>Class Diagram Example: Relationships Inference</ti><fi>ceg-infer</fi></ch>
diff --git a/doc/note.java b/doc/note.java
new file mode 100644
index 0000000..1c5944f
--- /dev/null
+++ b/doc/note.java
@@ -0,0 +1,26 @@
+/**
+ * @opt shape node
+ * @note Located in the
+ * machine room
+ * @note Sun Blade 6048
+ * @depend - - - MapLocation
+ * @depend - - - DataMine
+ */
+class Server{}
+
+/** @opt shape component */
+class MapLocation {}
+
+/** @opt shape component */
+class DataMine {}
+
+/**
+ * CPU-munching
+ * components that must
+ * run on this server
+ * @opt shape note
+ * @opt commentname
+ * @assoc - - - MapLocation
+ * @assoc - - - DataMine
+ */
+class munchComment {}
diff --git a/doc/shapes.java b/doc/shapes.java
new file mode 100644
index 0000000..c5f7718
--- /dev/null
+++ b/doc/shapes.java
@@ -0,0 +1,67 @@
+/**
+ * @hidden
+ * @opt nodefontcolor "blue"
+ */
+class UMLNoteOptions{}
+
+/**
+ * Structural Things
+ * @opt commentname
+ * @note Notes can
+ * be extended to
+ * span multiple lines
+ */
+class Structural{}
+
+/**
+ * spelling.java
+ * @opt shape component
+ * @opt commentname
+ * @note Component
+ */
+class Component extends Structural{}
+
+/** @opt shape node */
+class Node extends Structural{}
+
+/**
+ * Chain of
+ * responsibility
+ * @opt shape collaboration
+ * @opt commentname
+ * @note Collaboration
+ */
+class Collaboration extends Structural{}
+
+/**
+ * Place order
+ * @opt shape usecase
+ * @opt commentname
+ * @note Use Case
+ */
+class UseCase extends Structural{}
+
+/**
+ * Business rules
+ * @opt shape package
+ * @opt commentname
+ * @note Package
+ */
+class Package{}
+
+/**
+ * @opt all
+ * @note Class
+ */
+class Counter extends Structural {
+	static public int counter;
+	public int getCounter();
+}
+
+/**
+ * @opt shape activeclass
+ * @opt all
+ * @note Active Class
+ */
+class RunningCounter extends Counter{}
+
diff --git a/doc/ver.xml b/doc/ver.xml
index d086388..d2e7915 100644
--- a/doc/ver.xml
+++ b/doc/ver.xml
@@ -4,6 +4,9 @@
 <dl>
 
 <dt>Version 5.0 Under development </dt><dd>
+</dd>
+
+<dt>Version 5.0 2007-11-29 </dt><dd>
 <ul>
 <li> All code now lives under <code>org.umlgraph</code>.
 This change requires corresponding modifications to the UMLGraph
@@ -12,9 +15,11 @@ callers.</li>
 usecase, and activeclass.
 These shapes require GraphViz 1.16 or newer.
 </li>
-<li> A new @note tag allows the annotation of elements with comments.
+<li> A new <code>@note</code> tag allows the annotation of elements with comments.
 (Suggested by Sébastien Pierre.)
 </li>
+<li> A new <code>@commentname</code> option allows the naming of elements
+with the text of the <em>javadoc</em> comment.
 </ul>
 </dd>
 
diff --git a/doc/views.xml b/doc/views.xml
index 9d2ade4..f9a3e5c 100644
--- a/doc/views.xml
+++ b/doc/views.xml
@@ -42,7 +42,6 @@ class documentation for details on a proper regular expression specification.
 unless the "output" option is specified to override it.
 
 <h2>View inheritance</h2>
-
 View classes can inherit from other view classes, allowing views to
 share a set of common matches. The standard java inheritance mechanism
 is used to specify inheritance.<br/>