From 3700ff6322b10b5585885c76f5bd092d9a740b93 Mon Sep 17 00:00:00 2001 From: Andrea Aime Date: Fri, 30 Dec 2005 17:49:14 +0000 Subject: [PATCH] View support doc improvements (still incomplete) --- doc/RootViews.java | 67 +++++++++++++++++++ doc/ceg-mvi.xml | 162 ++++++++++++++++++++++++++++++++++----------- 2 files changed, 190 insertions(+), 39 deletions(-) create mode 100644 doc/RootViews.java diff --git a/doc/RootViews.java b/doc/RootViews.java new file mode 100644 index 0000000..880cc8c --- /dev/null +++ b/doc/RootViews.java @@ -0,0 +1,67 @@ +// 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 {} \ No newline at end of file diff --git a/doc/ceg-mvi.xml b/doc/ceg-mvi.xml index 38d11ca..1f4f114 100644 --- a/doc/ceg-mvi.xml +++ b/doc/ceg-mvi.xml @@ -6,48 +6,132 @@ 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 what makes it interesting is the ability to specify package based overrides that allow to adopt different options based on the package the classes are in. -The general syntax of an override is: - -/** - * @opt_override REGEXP ([!]option)* - */ - -where -

-A ! before the option disables the option for the specified package. -

-For example: - -/** - * @opt_override net.test.* !operations types - */ - -will add type information and disable the listing of operations for every class in the net.test package (and its subpackages).

-Multiple overrides can be specified in the same view, and they will be evaluated in the order they are specified -(so, the last one wins in case of conflict). -For example: +but what makes it interesting is the ability to specify package based +overrides that allow to adopt different options based on the package the classes are in. +The general syntax for defining a view is: /** * @view - * @hidden - * @opt_override .* hideall - * @opt_override net.test1.* !hideall - * @opt_override net.test2.* !hideall attributes operations visibility + * @opt [!]viewOption1 + * @opt [!]viewOption2 + * @match regularExpression1 + * @opt [!]option1.1 [argument] + * @opt [!]option1.2 [argument] + * ... + * @match regularExpression2 + * @opt [!]option2.1 [argument] + * @opt [!]option2.2 [argument] + * ... */ -class NetTest2PackageDiagram {} -defines a class diagram for the net.test2 package. -Everything in this package is shown, classes in the net.test1 package are shown as well, -but without details (probably because they are somewhat related to the net.test2 classes), the rest is hidden.

-Each view will generate a .dot file whose name is the name of the view (only the class name). Use the -d command line -parameter to specify in which folder the .dot files should be generated. -If you're wondering why we used ".*" as the regular expression to hide all the classes (and not simply *), that's because -the specification is not a filename globbing pattern, but a Java regular expression: -see the Pattern class documentation for further details. + +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. + +

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

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. Add ant/make automation and the project class diagram will +always be up to date. + +Postponed until I have finished the association/dependency inference + so that I don't have to modify source files to generate class diagrams + +