Guide‎ > ‎Logicdoc‎ > ‎

Logicdoc Operations

The gadget spec URL could not be found

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.

Logicdoc Operations

While Logicdoc is for documentation and contains no runtime code, it does provide some services you may wish to employ.


Installation

Follow this procedure to Logicdoc Installation, and verify its operation.


Building UseCase Classes

The UseCase Classes you build must adhere to the following:
  1. They must be written in Java
  2. They must employ the @UseCaseDoc and @Requirement annotations as illustrated above
  3. You may find it useful to integrate Logicdoc with jUnit tests
        i.e., identify the rules expected to solve each jUnit @Test

Logicdoc Contents

Logicdoc is delivered with:
  • Ant Script
You run Logicdoc via the LogicDoc Ant script, as described below.


Running LogicDoc


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
ProcessJava package
Use CaseJava Class (Logicdoc Use Case Class)1. Annotate the class with @UseCaseDoc

2. Consider naming conventions

  • Place them in packages corresponding to Processes

  • As shown below, BusLogIntro uses
    <DomainObject>_<Operation>[_<Qualification>]
RequirementJava method (LogicdocRequirement Method
  • These classes/methods are not executable - they are just for documentation

1. Annotate the Requirement with @Requirement

2. Document the Requirement with Javadoc
  • This is the shared understanding of Business and IT
3. Create @see references to Business Logic Component Logic Methods 
  • Follow with annotation comments: @see #note [:][*]
means indent, * means dot-point

4. Provide Javadoc summaries for your Business Logic Methods
  • 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.

Comments