diff --git a/doc/cd-opt.xml b/doc/cd-opt.xml index 977275c..ef35791 100644 --- a/doc/cd-opt.xml +++ b/doc/cd-opt.xml @@ -70,17 +70,32 @@ in this case it will hide everything (useful in the context of views to selectively unhide some portions of the graph, see the view chapter for further details). -
-hideall
Hide all entities from the graph. -Used with views to show only a specific -subset of classes in each class diagram. -
-d
Destination folder for .dot files generated from views.
-
-view
Specify the fully qualified name of a class that contains a view definition. -Only the class diagram specified by this view will be generated. +
-view
Specify the fully qualified name of a class that contains +a view definition. Only the class diagram specified by this view will be generated. +
See the views chapter for more details.
-views
Generate a class diagram for every view found in the source path.
+
-inferrel
Try to automatically infer relationships between classes by inspecting +field values. See the class diagram inference chapter for further details. Disabled by default. +
+
-inferreltype
The type of relationship inferred when -inferrel is activated. +Defaults to "navassoc" (see the class modelling chapter for a list of relationship types). +
+
-inferdep
Try to automatically infer dependencies between classes by inspecting +methods and fields. See the class diagram inference chapter for more details. Disabled by default. +
+
-useimports
Will also use imports to infer dependencies. +Disabled by default, since it does not work properly if there are multiple +classes in the same source file (will add dependencies to every class in +the source file). +
+
-collpackages
Specify the classes that will be treated as +containers for one to many relationships when inference is enabled. +Matching is done using a non-anchored regular match. Empty by default. +
-apidocroot
Specify the URL that should be used as the "root" for local classes. This URL will be used as a prefix, to which the page name for the local class or package will be appended (following the JavaDoc convention). @@ -113,7 +128,8 @@ a tripple specifying hue-saturation-brightness as values 0-1 or a tripple specifying red-green-blue values as hexadecimal digits prefixed by a # (e.g. "#ff8020"). The symbolic color names are derived from the X Windows System; -you can find a complete list in the Graphviz documentation. +you can find a complete list in the +Graphviz documentation

Font names are passed directly to the dot graph generation back-end. In general the Postcript standard names Times, Helvetica, Courier, and diff --git a/doc/ceg-mvi.xml b/doc/ceg-mvi.xml index 1f4f114..de99b94 100644 --- a/doc/ceg-mvi.xml +++ b/doc/ceg-mvi.xml @@ -6,14 +6,15 @@ 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. +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 regularExpression1 * @opt [!]option1.1 [argument] * @opt [!]option1.2 [argument] @@ -37,6 +38,15 @@ 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 @@ -127,11 +137,106 @@ dot -Tpng -o root.png DetailedView.dot 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. +consistent way.
-Postponed until I have finished the association/dependency inference - so that I don't have to modify source files to generate class diagrams - +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 inferassoc + * @opt inferdep + * @opt useimports + * + * @match .* + * @opt nodefillcolor LightGray + * + * @match org.apache.commons.* + * @opt nodefillcolor PaleGreen + * + * @match org.apache.commons.dbcp.* + * @opt nodefillcolor LemonChiffon + * + * @match java.*|org.xml.* + * @opt hide + * + * @match java.sql.* + * @opt !hide + * + * @match 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 org.apache.commons.* + * @opt hide + * + * @match org.apache.commons.dbcp..* + * @opt !hide + * + * @match 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 org.apache.commons.* + * @opt hide + * + * @match org.apache.commons.dbcp\..*Statement.* + * @opt !hide + * + * @match org.apache.commons.dbcp..*\..* + * @opt hide + */ +public class Statement extends BaseView { +} + + +Statement diff --git a/doc/dbcp-full.png b/doc/dbcp-full.png new file mode 100644 index 0000000..fb1423d Binary files /dev/null and b/doc/dbcp-full.png differ diff --git a/doc/dbcp-overview-full.png b/doc/dbcp-overview-full.png new file mode 100644 index 0000000..93357b5 Binary files /dev/null and b/doc/dbcp-overview-full.png differ diff --git a/doc/dbcp-overview-small.png b/doc/dbcp-overview-small.png new file mode 100644 index 0000000..ccecf86 Binary files /dev/null and b/doc/dbcp-overview-small.png differ diff --git a/doc/dbcp-small.png b/doc/dbcp-small.png new file mode 100644 index 0000000..73b4ce0 Binary files /dev/null and b/doc/dbcp-small.png differ diff --git a/doc/dbcp-statement.png b/doc/dbcp-statement.png new file mode 100644 index 0000000..eb23bca Binary files /dev/null and b/doc/dbcp-statement.png differ