mirror of https://github.com/dspinellis/UMLGraph
Split views into description and examples
This commit is contained in:
Diomidis Spinellis
parent
12821f9ed9
commit
9be890d3b8
251
doc/ceg-mvi.xml
251
doc/ceg-mvi.xml
|
|
@ -1,251 +0,0 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!-- $Id$ -->
|
||||
<notes>
|
||||
Documenting a big project often requires multiple diagrams:
|
||||
each to show a specific and limited portion of the system.
|
||||
Each diagram is usually composed of few classes, possibily using a different detail level.<p/>
|
||||
The <code>@view</code> tag, marks a special class used to describe a single class diagram.
|
||||
Similarly to UMLOptions, the view can define its own general options,
|
||||
but allows to define <em>overrides</em> that allow to adopt different options
|
||||
for different classes based on regular expressions matching.
|
||||
The general syntax for defining a view is:
|
||||
<fmtcode ext="java">
|
||||
/**
|
||||
* @view
|
||||
* @opt [!]viewOption1
|
||||
* @opt [!]viewOption2
|
||||
* ...
|
||||
* @match matchtype regularExpression1
|
||||
* @opt [!]option1.1 [argument]
|
||||
* @opt [!]option1.2 [argument]
|
||||
* ...
|
||||
* @match matchtype regularExpression2
|
||||
* @opt [!]option2.1 [argument]
|
||||
* @opt [!]option2.2 [argument]
|
||||
* ...
|
||||
*/
|
||||
</fmtcode>
|
||||
|
||||
At the moment UMLGraph supports only the 'class' match type, in the future
|
||||
other types of match will be added (tags, implemented interfaces,
|
||||
superclasses, just to name a few possibilities).<br/>
|
||||
The view options are applied to every class in the view (so they are the
|
||||
global options for this class diagram).<br/>
|
||||
The regular expression will be used to match a single class, a group of
|
||||
classes, or a package, and the options that follow will be applied to
|
||||
those classes. <br/>
|
||||
Multiple matches will be evaluted in the order of specification.<br/>
|
||||
Refer to the <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">Pattern</a>
|
||||
class documentation for details on a proper regular expression specification.
|
||||
|
||||
<p/>Each view will generate a .dot file whose name is the name of the view,
|
||||
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/>
|
||||
Abstract view classes won't be used to generate diagrams, the common
|
||||
idiom is to declare a base abstract view to share common options and
|
||||
overrides, and have concrete view classes that extend for diagram generation.
|
||||
|
||||
<h2>Example: views at different detail of specification</h2>
|
||||
|
||||
The previous multiple view example can be generated by using internal
|
||||
view support by means of the following sources (note the use of UmlOptions
|
||||
to set the common appearance options, and the views to generate multiple
|
||||
diagrams at different detail level).
|
||||
|
||||
<fmtcode ext="java">
|
||||
// Author: Vadim Nasardinov
|
||||
// Author: Andrea Aime
|
||||
// Version: $Id$
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* @assoc "1..1" - "0..n" Adapter
|
||||
* @assoc "" - "0..n" ObjectType
|
||||
* @assoc "" - "0..n" ObjectMap
|
||||
* @assoc "" - "0..n" Table
|
||||
* @assoc "" - "0..n" DataOperation
|
||||
**/
|
||||
class Root {
|
||||
private Map m_adapters;
|
||||
private List m_types;
|
||||
private List m_maps;
|
||||
private List m_tables;
|
||||
private List m_ops;
|
||||
|
||||
public Adapter getAdapter(Class klass) {}
|
||||
}
|
||||
|
||||
class Adapter {
|
||||
public Root getRoot();
|
||||
}
|
||||
|
||||
abstract class Element {
|
||||
Root getRoot() {}
|
||||
}
|
||||
|
||||
class ObjectType extends Element {}
|
||||
|
||||
/**
|
||||
* @has "1..1" - "1..1" ObjectType
|
||||
**/
|
||||
class ObjectMap extends Element {
|
||||
private ObjectType m_type;
|
||||
}
|
||||
|
||||
class Table extends Element {}
|
||||
|
||||
class DataOperation extends Element {}
|
||||
|
||||
/**
|
||||
* @hidden
|
||||
* @opt nodefontname luxisr
|
||||
* @opt nodefontabstractname luxisri
|
||||
* @opt edgefontname luxisr
|
||||
* @opt nodefontsize 8
|
||||
* @opt edgefontsize 8
|
||||
* @opt nodefillcolor LemonChiffon
|
||||
*/
|
||||
class UMLOptions {}
|
||||
|
||||
/**
|
||||
* @view
|
||||
* @opt attributes
|
||||
* @opt operations
|
||||
*/
|
||||
class DetailedView {}
|
||||
|
||||
/**
|
||||
* @view
|
||||
*/
|
||||
class Overview {}
|
||||
</fmtcode>
|
||||
|
||||
and by invoking the following commands (assuming UmlGraph.jar is in the
|
||||
current directory):
|
||||
|
||||
<fmtcode ext="bat">
|
||||
javadoc -doclet gr.spinellis.umlgraph.doclet.UmlGraph -private -docletpath UmlGraph.jar -views RootViews.java
|
||||
dot -Tpng -o root-small.png Overview.dot
|
||||
dot -Tpng -o root.png DetailedView.dot
|
||||
</fmtcode>
|
||||
|
||||
The javadoc invocation asks UMLGraph to build a diagram for every view (-views)
|
||||
contained in the RootViews.java file. Notably, there's no class RootViews
|
||||
in the source file: this is not needed to make javadoc work on a single
|
||||
class. Respecting the java rules for file and class naming is anyway advised
|
||||
in any real situation.
|
||||
|
||||
<h2>Example: per package views</h2>
|
||||
|
||||
Views are especially interesting in big projects, since they allow to
|
||||
generate package specific diagrams and overview diagrams in a quick and
|
||||
consistent way. <br/>
|
||||
|
||||
As an example we include a few class diagrams that have been generated
|
||||
from the <a href="http://jakarta.apache.org/commons/dbcp">DBCP connection pool</a>,
|
||||
without altering the sources and using association and dependency inference
|
||||
instead.<br/>
|
||||
|
||||
The base view defines commons options, in particular the use of inference,
|
||||
common class coloring and class visibility (in particular, we hide the
|
||||
java runtime classes, with the exclusion of a few java.sql classes).
|
||||
To avoid visual clutter, we have first shown the java.sql package contents, and
|
||||
then hid selected classes.
|
||||
The <code>Overview</code> view provides a full view of the DBCP package,
|
||||
generating quite a big diagram (click on the diagram to show a full size version).<br/>
|
||||
|
||||
<fmtcode ext="java">
|
||||
package org.apache.commons;
|
||||
|
||||
/**
|
||||
* @view
|
||||
* @opt inferrel
|
||||
* @opt inferdep
|
||||
* @opt useimports
|
||||
*
|
||||
* @match class .*
|
||||
* @opt nodefillcolor LightGray
|
||||
*
|
||||
* @match class org.apache.commons.*
|
||||
* @opt nodefillcolor PaleGreen
|
||||
*
|
||||
* @match class org.apache.commons.dbcp.*
|
||||
* @opt nodefillcolor LemonChiffon
|
||||
*
|
||||
* @match class java.*|org.xml.*
|
||||
* @opt hide
|
||||
*
|
||||
* @match class java.sql.*
|
||||
* @opt !hide
|
||||
*
|
||||
* @match class java.sql\.(Ref|Time|Timestamp|Array|Date|Time|Clob|Blob|SQLException|.*MetaData.*|SQLWarning)
|
||||
* @opt hide
|
||||
*/
|
||||
public abstract class BaseView {
|
||||
}
|
||||
|
||||
/**
|
||||
* @view
|
||||
*/
|
||||
public class Overview extends BaseView {
|
||||
}
|
||||
</fmtcode>
|
||||
|
||||
<a href="dbcp-overview-full.png"><img src="dbcp-overview-small.png" alt="Overview"/></a>
|
||||
|
||||
<p/>The <code>CommonsDbcp</code> view concentrates on the content of org.apache.commons.dbcp
|
||||
package, hiding other packages and subpackages available in the sources
|
||||
(click on the diagram to show a full size version).<br/>
|
||||
|
||||
<fmtcode ext="java">
|
||||
package org.apache.commons;
|
||||
|
||||
/**
|
||||
* @view
|
||||
*
|
||||
* @match class org.apache.commons.*
|
||||
* @opt hide
|
||||
*
|
||||
* @match class org.apache.commons.dbcp..*
|
||||
* @opt !hide
|
||||
*
|
||||
* @match class org.apache.commons.dbcp..*\..*
|
||||
* @opt hide
|
||||
*/
|
||||
public class CommonsDbcp extends BaseView {}
|
||||
</fmtcode>
|
||||
|
||||
<a href="dbcp-full.png"><img src="dbcp-small.png" alt="Overview"/></a>
|
||||
|
||||
<p/>Finally, the <code>Statement</code> view shows only the Statement related
|
||||
classes and their dependencies.
|
||||
|
||||
<fmtcode ext="java">
|
||||
package org.apache.commons;
|
||||
|
||||
/**
|
||||
* @view
|
||||
*
|
||||
* @match class org.apache.commons.*
|
||||
* @opt hide
|
||||
*
|
||||
* @match class org.apache.commons.dbcp\..*Statement.*
|
||||
* @opt !hide
|
||||
*
|
||||
* @match class org.apache.commons.dbcp..*\..*
|
||||
* @opt hide
|
||||
*/
|
||||
public class Statement extends BaseView {
|
||||
}
|
||||
</fmtcode>
|
||||
|
||||
<img src="dbcp-statement.png" alt="Statement"/>
|
||||
|
||||
</notes>
|
||||
|
|
@ -0,0 +1,93 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!-- $Id$ -->
|
||||
<notes>
|
||||
The makefile-based multiple view example can be generated by using internal
|
||||
view support by means of the following sources (note the use of UmlOptions
|
||||
to set the common appearance options, and the views to generate multiple
|
||||
diagrams at different detail level).
|
||||
|
||||
<fmtcode ext="java">
|
||||
// Author: Vadim Nasardinov
|
||||
// Author: Andrea Aime
|
||||
// Version: $Id$
|
||||
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* @assoc "1..1" - "0..n" Adapter
|
||||
* @assoc "" - "0..n" ObjectType
|
||||
* @assoc "" - "0..n" ObjectMap
|
||||
* @assoc "" - "0..n" Table
|
||||
* @assoc "" - "0..n" DataOperation
|
||||
**/
|
||||
class Root {
|
||||
private Map m_adapters;
|
||||
private List m_types;
|
||||
private List m_maps;
|
||||
private List m_tables;
|
||||
private List m_ops;
|
||||
|
||||
public Adapter getAdapter(Class klass) {}
|
||||
}
|
||||
|
||||
class Adapter {
|
||||
public Root getRoot();
|
||||
}
|
||||
|
||||
abstract class Element {
|
||||
Root getRoot() {}
|
||||
}
|
||||
|
||||
class ObjectType extends Element {}
|
||||
|
||||
/**
|
||||
* @has "1..1" - "1..1" ObjectType
|
||||
**/
|
||||
class ObjectMap extends Element {
|
||||
private ObjectType m_type;
|
||||
}
|
||||
|
||||
class Table extends Element {}
|
||||
|
||||
class DataOperation extends Element {}
|
||||
|
||||
/**
|
||||
* @hidden
|
||||
* @opt nodefontname luxisr
|
||||
* @opt nodefontabstractname luxisri
|
||||
* @opt edgefontname luxisr
|
||||
* @opt nodefontsize 8
|
||||
* @opt edgefontsize 8
|
||||
* @opt nodefillcolor LemonChiffon
|
||||
*/
|
||||
class UMLOptions {}
|
||||
|
||||
/**
|
||||
* @view
|
||||
* @opt attributes
|
||||
* @opt operations
|
||||
*/
|
||||
class DetailedView {}
|
||||
|
||||
/**
|
||||
* @view
|
||||
*/
|
||||
class Overview {}
|
||||
</fmtcode>
|
||||
|
||||
and by invoking the following commands (assuming UmlGraph.jar is in the
|
||||
current directory):
|
||||
|
||||
<fmtcode ext="bat">
|
||||
javadoc -doclet gr.spinellis.umlgraph.doclet.UmlGraph -private -docletpath UmlGraph.jar -views RootViews.java
|
||||
dot -Tpng -o root-small.png Overview.dot
|
||||
dot -Tpng -o root.png DetailedView.dot
|
||||
</fmtcode>
|
||||
|
||||
The javadoc invocation asks UMLGraph to build a diagram for every view (-views)
|
||||
contained in the RootViews.java file. Notably, there's no class RootViews
|
||||
in the source file: this is not needed to make javadoc work on a single
|
||||
class. Respecting the java rules for file and class naming is anyway advised
|
||||
in any real situation.
|
||||
</notes>
|
||||
|
|
@ -0,0 +1,109 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!-- $Id$ -->
|
||||
<notes>
|
||||
Views are especially interesting in big projects, since they allow to
|
||||
generate package specific diagrams and overview diagrams in a quick and
|
||||
consistent way. <br/>
|
||||
|
||||
As an example we include a few class diagrams that have been generated
|
||||
from the <a href="http://jakarta.apache.org/commons/dbcp">DBCP connection pool</a>,
|
||||
without altering the sources and using association and dependency inference
|
||||
instead.<br/>
|
||||
|
||||
The base view defines commons options, in particular the use of inference,
|
||||
common class coloring and class visibility (in particular, we hide the
|
||||
java runtime classes, with the exclusion of a few java.sql classes).
|
||||
To avoid visual clutter, we have first shown the java.sql package contents, and
|
||||
then hid selected classes.
|
||||
The <code>Overview</code> view provides a full view of the DBCP package,
|
||||
generating quite a big diagram (click on the diagram to show a full size version).<br/>
|
||||
|
||||
<fmtcode ext="java">
|
||||
package org.apache.commons;
|
||||
|
||||
/**
|
||||
* @view
|
||||
* @opt inferrel
|
||||
* @opt inferdep
|
||||
* @opt useimports
|
||||
*
|
||||
* @match class .*
|
||||
* @opt nodefillcolor LightGray
|
||||
*
|
||||
* @match class org.apache.commons.*
|
||||
* @opt nodefillcolor PaleGreen
|
||||
*
|
||||
* @match class org.apache.commons.dbcp.*
|
||||
* @opt nodefillcolor LemonChiffon
|
||||
*
|
||||
* @match class java.*|org.xml.*
|
||||
* @opt hide
|
||||
*
|
||||
* @match class java.sql.*
|
||||
* @opt !hide
|
||||
*
|
||||
* @match class java.sql\.(Ref|Time|Timestamp|Array|Date|Time|Clob|Blob|SQLException|.*MetaData.*|SQLWarning)
|
||||
* @opt hide
|
||||
*/
|
||||
public abstract class BaseView {
|
||||
}
|
||||
|
||||
/**
|
||||
* @view
|
||||
*/
|
||||
public class Overview extends BaseView {
|
||||
}
|
||||
</fmtcode>
|
||||
|
||||
<a href="dbcp-overview-full.png"><img src="dbcp-overview-small.png" alt="Overview"/></a>
|
||||
|
||||
<p/>The <code>CommonsDbcp</code> view concentrates on the content of org.apache.commons.dbcp
|
||||
package, hiding other packages and subpackages available in the sources
|
||||
(click on the diagram to show a full size version).<br/>
|
||||
|
||||
<fmtcode ext="java">
|
||||
package org.apache.commons;
|
||||
|
||||
/**
|
||||
* @view
|
||||
*
|
||||
* @match class org.apache.commons.*
|
||||
* @opt hide
|
||||
*
|
||||
* @match class org.apache.commons.dbcp..*
|
||||
* @opt !hide
|
||||
*
|
||||
* @match class org.apache.commons.dbcp..*\..*
|
||||
* @opt hide
|
||||
*/
|
||||
public class CommonsDbcp extends BaseView {}
|
||||
</fmtcode>
|
||||
|
||||
<a href="dbcp-full.png"><img src="dbcp-small.png" alt="Overview"/></a>
|
||||
|
||||
<p/>Finally, the <code>Statement</code> view shows only the Statement related
|
||||
classes and their dependencies.
|
||||
|
||||
<fmtcode ext="java">
|
||||
package org.apache.commons;
|
||||
|
||||
/**
|
||||
* @view
|
||||
*
|
||||
* @match class org.apache.commons.*
|
||||
* @opt hide
|
||||
*
|
||||
* @match class org.apache.commons.dbcp\..*Statement.*
|
||||
* @opt !hide
|
||||
*
|
||||
* @match class org.apache.commons.dbcp..*\..*
|
||||
* @opt hide
|
||||
*/
|
||||
public class Statement extends BaseView {
|
||||
}
|
||||
</fmtcode>
|
||||
|
||||
<img src="dbcp-statement.png" alt="Statement"/>
|
||||
|
||||
</notes>
|
||||
|
||||
|
|
@ -6,6 +6,7 @@
|
|||
<ch><ti>Class Diagram Operations</ti><fi>cd-oper</fi></ch>
|
||||
<ch><ti>Class Modelling</ti><fi>cd-model</fi></ch>
|
||||
<ch><ti>Class Diagram Options</ti><fi>cd-opt</fi></ch>
|
||||
<ch><ti>Class Diagram Views</ti><fi>views</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>
|
||||
|
|
@ -16,7 +17,8 @@
|
|||
<ch><ti>Class Diagram Example: Class Stereotypes and Tagged Values</ti><fi>ceg-ster</fi></ch>
|
||||
<ch><ti>Class Diagram Example: Colors, Global and Local Options</ti><fi>ceg-color</fi></ch>
|
||||
<ch><ti>Class Diagram Example: Multiple Views Through Command-Line Options</ti><fi>ceg-mv</fi></ch>
|
||||
<ch><ti>Class Diagram Example: Multiple Views Using the Built-in Support</ti><fi>ceg-mvi</fi></ch>
|
||||
<ch><ti>Class Diagram Example: Views With Different Specification Details</ti><fi>ceg-view-details</fi></ch>
|
||||
<ch><ti>Class Diagram Example: Views for Different Packages</ti><fi>ceg-view-packages</fi></ch>
|
||||
<ch><ti>Running the Doclet from Ant</ti><fi>ant</fi></ch>
|
||||
<ch><ti>Sequence Diagrams</ti><fi>seq-intro</fi></ch>
|
||||
<ch><ti>Syntax of Sequence Diagram Definitions</ti><fi>seq-syntax</fi></ch>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,53 @@
|
|||
<?xml version="1.0" ?>
|
||||
<!-- $Id$ -->
|
||||
<notes>
|
||||
Documenting a big project often requires multiple diagrams:
|
||||
each to show a specific and limited portion of the system.
|
||||
Each diagram is usually composed of few classes, possibily using a different detail level.<p/>
|
||||
The <code>@view</code> tag, marks a special class used to describe a single class diagram.
|
||||
Similarly to UMLOptions, the view can define its own general options,
|
||||
but allows to define <em>overrides</em> that allow to adopt different options
|
||||
for different classes based on regular expressions matching.
|
||||
The general syntax for defining a view is:
|
||||
<fmtcode ext="java">
|
||||
/**
|
||||
* @view
|
||||
* @opt [!]viewOption1
|
||||
* @opt [!]viewOption2
|
||||
* ...
|
||||
* @match matchtype regularExpression1
|
||||
* @opt [!]option1.1 [argument]
|
||||
* @opt [!]option1.2 [argument]
|
||||
* ...
|
||||
* @match matchtype regularExpression2
|
||||
* @opt [!]option2.1 [argument]
|
||||
* @opt [!]option2.2 [argument]
|
||||
* ...
|
||||
*/
|
||||
</fmtcode>
|
||||
|
||||
At the moment UMLGraph supports only the 'class' match type, in the future
|
||||
other types of match will be added (tags, implemented interfaces,
|
||||
superclasses, just to name a few possibilities).<br/>
|
||||
The view options are applied to every class in the view (so they are the
|
||||
global options for this class diagram).<br/>
|
||||
The regular expression will be used to match a single class, a group of
|
||||
classes, or a package, and the options that follow will be applied to
|
||||
those classes. <br/>
|
||||
Multiple matches will be evaluted in the order of specification.<br/>
|
||||
Refer to the <a href="http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html">Pattern</a>
|
||||
class documentation for details on a proper regular expression specification.
|
||||
|
||||
<p/>Each view will generate a .dot file whose name is the name of the view,
|
||||
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/>
|
||||
Abstract view classes won't be used to generate diagrams, the common
|
||||
idiom is to declare a base abstract view to share common options and
|
||||
overrides, and have concrete view classes that extend for diagram generation.
|
||||
|
||||
</notes>
|
||||
Loading…
Reference in New Issue