Logicdoc provides transparency, enabling you to define Use Case Requirements in format suitable for Business Users to read, and provides traceability from a Requirement to the Rules that implement it. An example is shown below from the full Logidoc which you can explore here.
Logicdoc is an extension of Java/Groovydoc based on Enhanced Groovy Doc that generates documentation for your Business Logic Components and your Domain Objects, including graphical UML diagrams.
Logicdoc is entirely optional, and can be used at any stage:
- during analysis to document requirements
- at design time to document the logic intention
- at maintenance time to recapture design intent
Please review the Architecture
before reading this document.
While Logicdoc is for documentation and contains no runtime code, it does provide some services you may wish to employ.
Follow this procedure to Logicdoc Installation, and verify its operation.
Building UseCase Classes
The UseCase Classes you build must adhere to the following:
- They must be written in Java
- They must employ the
@Requirement annotations as illustrated above
- You may find it useful to integrate Logicdoc with jUnit tests
i.e., identify the rules expected to solve each jUnit
Logicdoc is delivered with:
You run Logicdoc via the
LogicDoc Ant script, as described below.
To prepare LogicDoc:
- Copy the supplied
Logicdoc Ant script to your project (e.g.,
BusLogicIntro uses the
Build folder), and
- Alter it per your configuration as described therein.
Run the Ant script... e.g., in Eclipse:
- Open the script
- Open an Outline View
- In the Outline view, right click on
LogicDoc , and
Run As => Ant Build
- By default, output is created in your projects'
doc folder As usual,
index.html opens the result
- Execution also generates
export/BusLogicDoc.txt, which is a tab delimited file. You can import this into a number of products, such as Microsoft Project (TM), MindMeister (TM), FreeMind (TM), and many others
How is Logicdoc used
Since Business Logic is specified in Java/Groovy Logic Methods, normal use of Java/Groovydoc generates documentation for Domain Objects and Business Logic Components. You will, of course, get UMLGraphs for your domain packages.
To capture Requirements and their logic Traceability, create documentation-only Use Case Classes and Requirement Methods:
|Analysis Concept ||Logicdoc: create in Java...|| Notes|
|Use Case||Java Class (Logicdoc Use Case Class)||1. Annotate the class with |
2. Consider naming conventions
- Place them in packages corresponding to Processes
- As shown below, BusLogIntro uses
|Requirement||Java method (LogicdocRequirement Method) |
- These classes/methods are not executable - they are just for documentation
|1. Annotate the Requirement with |
2. Document the Requirement with Javadoc
- This is the shared understanding of Business and IT
@see references to Business Logic Component Logic Methods
- Follow with annotation comments: @see #note [:][*]
4. Provide Javadoc summaries for your Business Logic Methods
: means indent,
* means dot-point
- Often not necessary for sums/counts per system defaults
- For formulas/constraints, this is usually the expression, perhaps omitting null checking
Here is an example of a Use Case Class
You may wonder about the code at the bottom. It is (certainly!) not executable. It is merely to create a reference to the Logic Method, to take advantage of IDE features:
- Hover to see Javadoc (shown)
- Jump to Logic Method (e.e.g, F3 on Eclipse)
- In a typical Use Case, your code is "spread out" amongst different Business Logic Components, so this provides a good way to see these in one place, with quick access links
For more in mapping Logicdoc your own process / terminology, click here