diff --git a/doc/ceg-mvi.xml b/doc/ceg-mvi.xml deleted file mode 100644 index 52ffdf1..0000000 --- a/doc/ceg-mvi.xml +++ /dev/null @@ -1,251 +0,0 @@ - - - -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.

-The @view 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 overrides that allow to adopt different options -for different classes based on regular expressions matching. -The general syntax for defining a view is: - -/** - * @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] - * ... - */ - - -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).
-The view options are applied to every class in the view (so they are the -global options for this class diagram).
-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.
-Multiple matches will be evaluted in the order of specification.
-Refer to the Pattern -class documentation for details on a proper regular expression specification. - -

Each view will generate a .dot file whose name is the name of the view, -unless the "output" option is specified to override it. - -

View inheritance

- -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.
-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. - -

Example: views at different detail of specification

- -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). - - -// 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 {} - - -and by invoking the following commands (assuming UmlGraph.jar is in the -current directory): - - -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 - - -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. - -

Example: per package views

- -Views are especially interesting in big projects, since they allow to -generate package specific diagrams and overview diagrams in a quick and -consistent way.
- -As an example we include a few class diagrams that have been generated -from the DBCP connection pool, -without altering the sources and using association and dependency inference -instead.
- -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 Overview view provides a full view of the DBCP package, -generating quite a big diagram (click on the diagram to show a full size version).
- - -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 { -} - - -Overview - -

The CommonsDbcp 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).
- - -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 {} - - -Overview - -

Finally, the Statement view shows only the Statement related -classes and their dependencies. - - -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 { -} - - -Statement - - diff --git a/doc/ceg-view-details.xml b/doc/ceg-view-details.xml new file mode 100644 index 0000000..79ee356 --- /dev/null +++ b/doc/ceg-view-details.xml @@ -0,0 +1,93 @@ + + + +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). + + +// 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 {} + + +and by invoking the following commands (assuming UmlGraph.jar is in the +current directory): + + +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 + + +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. + diff --git a/doc/ceg-view-packages.xml b/doc/ceg-view-packages.xml new file mode 100644 index 0000000..3ac9f99 --- /dev/null +++ b/doc/ceg-view-packages.xml @@ -0,0 +1,109 @@ + + + +Views are especially interesting in big projects, since they allow to +generate package specific diagrams and overview diagrams in a quick and +consistent way.
+ +As an example we include a few class diagrams that have been generated +from the DBCP connection pool, +without altering the sources and using association and dependency inference +instead.
+ +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 Overview view provides a full view of the DBCP package, +generating quite a big diagram (click on the diagram to show a full size version).
+ + +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 { +} + + +Overview + +

The CommonsDbcp 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).
+ + +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 {} + + +Overview + +

Finally, the Statement view shows only the Statement related +classes and their dependencies. + + +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 { +} + + +Statement + + + diff --git a/doc/index.xml b/doc/index.xml index 03edd9d..2b5db23 100644 --- a/doc/index.xml +++ b/doc/index.xml @@ -6,6 +6,7 @@ Class Diagram Operationscd-oper Class Modellingcd-model Class Diagram Optionscd-opt +Class Diagram Viewsviews Class Diagram Example: Generalisation Relationshipsceg-gen Class Diagram Example: Advanced Relationshipsceg-adv Class Diagram Example: Relationships Inferenceceg-infer @@ -16,7 +17,8 @@ Class Diagram Example: Class Stereotypes and Tagged Valuesceg-ster Class Diagram Example: Colors, Global and Local Optionsceg-color Class Diagram Example: Multiple Views Through Command-Line Optionsceg-mv -Class Diagram Example: Multiple Views Using the Built-in Supportceg-mvi +Class Diagram Example: Views With Different Specification Detailsceg-view-details +Class Diagram Example: Views for Different Packagesceg-view-packages Running the Doclet from Antant Sequence Diagramsseq-intro Syntax of Sequence Diagram Definitionsseq-syntax diff --git a/doc/views.xml b/doc/views.xml new file mode 100644 index 0000000..9d2ade4 --- /dev/null +++ b/doc/views.xml @@ -0,0 +1,53 @@ + + + +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.

+The @view 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 overrides that allow to adopt different options +for different classes based on regular expressions matching. +The general syntax for defining a view is: + +/** + * @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] + * ... + */ + + +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).
+The view options are applied to every class in the view (so they are the +global options for this class diagram).
+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.
+Multiple matches will be evaluted in the order of specification.
+Refer to the Pattern +class documentation for details on a proper regular expression specification. + +

Each view will generate a .dot file whose name is the name of the view, +unless the "output" option is specified to override it. + +

View inheritance

+ +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.
+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. + +