From 7fe982d20efffeb2a111619e608458d49df4f26e Mon Sep 17 00:00:00 2001 From: Andrea Aime Date: Mon, 26 Dec 2005 21:14:23 +0000 Subject: [PATCH] View support documentation --- doc/cd-opt.xml | 12 +++++++++++- doc/ceg-mvi.xml | 33 +++++++++++++++++++++++++++++++++ doc/index.xml | 3 ++- doc/ver.xml | 3 +++ 4 files changed, 49 insertions(+), 2 deletions(-) create mode 100644 doc/ceg-mvi.xml diff --git a/doc/cd-opt.xml b/doc/cd-opt.xml index 9a7408d..6ad7216 100644 --- a/doc/cd-opt.xml +++ b/doc/cd-opt.xml @@ -65,11 +65,21 @@ Matching is done against the end of each entity's name. For instance, "-hide Widget" would hide "com.foo.widgets.Widget" and "com.foo.widgets.BigWidget". +
-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. +
+
-views
Look into the source path and generate a class diagram for every view that is found. +
-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). For example, if the value http://www.acme.org/apidocs is -provided, the class org.acme.util.MyClass will be mapped to the URL +provided, the class org.acme.util.MyClass will be mapped to the URL http://www.acme.org/apidocs/org/acme/util/MyClass.html. This URL will then be added to .dot diagram and can be surfaced in the final class diagram by setting the output to SVG, or by creating an HTML page diff --git a/doc/ceg-mvi.xml b/doc/ceg-mvi.xml new file mode 100644 index 0000000..559376a --- /dev/null +++ b/doc/ceg-mvi.xml @@ -0,0 +1,33 @@ + + + +Documenting a big project usually requires multiple diagrams, each design to show a specific and limited portion of the system. +Each diagram is usually composed of few classes, possibily using a different detail level.

+Following the approach of the UMLOptions class, we introduced the @view tag, that marks a special class used to describe a single class diagram. +Similarly to UMLOptions, the view can define his 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 REGEXP is a java regular expression that will match a single class, a group of classes, a package, and option is one of the UMLGraph options that +are usually specified with the @option tag. 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 operations listing 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 specification order (so, the last one wins in case of conflict). +For example: +

+/**
+ * @view
+ * @hidden
+ * @opt_override .* hideall
+ * @opt_override net.test1.* !hideall
+ * @opt_override net.test2.* !hideall attributes operations visibility
+ */
+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 better specify in which folder the .dot files should be generated. +Oh, if you're wondering why we used ".*" as the regular expression to hide all the classes (and not simply *), that's because +this is not a file system like wildcard, but a java regular expression: see the Pattern javadoc for further details. + diff --git a/doc/index.xml b/doc/index.xml index 34a5bb9..4bf4374 100644 --- a/doc/index.xml +++ b/doc/index.xml @@ -14,7 +14,8 @@ Class Diagram Example: Real Example (Catalina Classes)ceg-cat Class Diagram Example: Class Stereotypes and Tagged Valuesceg-ster Class Diagram Example: Colors, Global and Local Optionsceg-color -Class Diagram Example: Multiple Viewsceg-mv +Class Diagram Example: Multiple Views (command line)ceg-mv +Class Diagram Example: Multiple Views (internal support)ceg-mvi Sequence Diagramsseq-intro Syntax of Sequence Diagram Definitionsseq-syntax Defining a Simple Sequence Diagramseq-simple diff --git a/doc/ver.xml b/doc/ver.xml index 42c7acf..22afa78 100644 --- a/doc/ver.xml +++ b/doc/ver.xml @@ -9,6 +9,9 @@ the extends keyword (Arnaud Rogues).

  • Javadoc documentation (Andrea Aime).
  • Centralized option handling in the Option class (even for command line arguments) (Andrea Aime).
    • +
  • Addded "views", that is, the ability to specify package based option overrides in UMLOptions like classes, + and to generate multiple diagrams out of a code base in a single pass. See the new tags @view, @opt_override, + @hideall, and the command line parameters -d, -view, -views (Andrea Aime)
    • Version 4.1 2005/11/15