|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjaxb.MetaArchitectureDocument
public class MetaArchitectureDocument
This document explains how this architecture document is written.
All of the JAXB RI architecture document is built as javadoc. So contributing to this document means writing/modifying the javadoc and commiting it.
Using javadoc makes it easier to keep the documents in sync, thanks to modern IDEs, and it also allows us to link to various code pieces more easily.
The JAXB RI workspace contains a special 'javadoc' module, which is used exclusively for hosting architecture document javadoc. Normally, the architecture document is written on a package/class that provides the functionality, but this module can be used to write a part of the document that doesn't relate to any particular code (such as this document itself.)
The out-of-box javadoc tool lacks several features for writing documentations, so we wrote a few custom javadoc tags to enhance the expressiveness.
The ArchitectureDocument
tag is a block tag that can be written on
a class or a package. When present, it changes the way the javadoc is generated
for that class/package. Specifically, it brings the description page to the very
top of the HTML page (whereas normally the description is after the list of members.)
This improves the readability by eliminating the needs to scroll down.
The SequenceDiagram
tag is an inline tag that can be written anywhere.
This tag allows you to write an UML sequence diagram in a declarative fashion.
For example, the following javadoc will produce the following picture:
{@SequenceDiagram # Define the objects object(O,"o:Toolkit"); placeholder_object(P); step(); # Message sequences active(O); step(); active(O); message(O,O,"callbackLoop()"); inactive(O); create_message(O,P,"p:Peer"); message(O,P,"handleExpose()"); active(P); return_message(P,O,""); inactive(P); destroy_message(O,P); inactive(O); # Complete the lifelines step(); complete(O); }
For details about the syntax, see this document.
When you are writing a diagram, it's convenient to use a scratch pad (Sun-internal) to quickly check the output of your description.
The DotDiagram
tag is similar to the SequenceDiagram
tag in its concept.
It is an inline tag that can be written anywhere.
This tag allows you to write a box and arrow diagram by using
the dot program in the GraphViz package.
For example, the following javadoc will produce the following picture:
{@DotDiagram digraph G { size ="4,4"; main [shape=box]; // this is a comment main -> parse [weight=8]; parse -> execute; main -> init [style=dotted]; main -> cleanup; execute -> { make_string; printf} init -> make_string; edge [color=red]; // so is this main -> printf [style=bold,label="100 times"]; make_string [label="make a\nstring"]; node [shape=box,style=filled,color=".7 .3 1.0"]; execute -> compare; } }
For details about the syntax, see this document.
When you are writing a diagram, it's convenient to use a scratch pad (Sun-internal) to quickly check the output of your description.
To generate the document locally, run ant architecture-document
from the command line.
Because of the way the custom javadoc tags work, this only works for computers
running inside Sun.
Alternatively, Hudson automatically posts a new architecture document to the java.net every time a commit is made. This process typically takes 10 minutes (so in the worst case, it takes 20 minutes for your change to be reflected.)
The up-to-date version of the document is always available at the java.net.
Constructor Summary | |
---|---|
MetaArchitectureDocument()
|
Method Summary |
---|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Constructor Detail |
---|
public MetaArchitectureDocument()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |