search JMRI:

Development tools

• Getting the code via SVN
• SVN FAQs
• Building with Ant
• Building with NetBeans
• Building with XCode
• Building with Eclipse
• Building with JBuilder

Structure

• Introduction
• Application Structure
• Names and Naming
• Code Structure Patterns
• Swing Structure
• External Connection Structure
• Threads
• Use of XML
• Web Site
• JavaDocs
  • Name Index
  • Packages
  • Class heirarchy

Techniques and Standards

• Recommended Practices
• Continuous Integration
• Internationalization
• Logging & Error Handling
• Unit testing with JUnit
• Documentation with JavaDoc and UML
• Run the FindBugs static analysis tool
• Providing help with JavaHelp
• Portable Filename Method
• XML Persistance

How To

• Extend with Plugins
• Add a New Type
• Add a New System

Functional Info

• Turnout Feedback
• Network Connections
• How the startup scripts work

Background Info

• Technology Roadmap
• Survey of JVM Capabilities
• Usage Poll, Spring 2007

JMRI: Use of JavaDoc and UML

The JMRI library provides the majority of its API documentation via JavaDoc and UML.

We also use Java annotations to document our code structure.

We use the UmlGraph doclet to automatically create the UML diagrams in our JavaDoc pages.

JavaDoc for Developers

The JavaDoc tutorial is a good, but somewhat long, introduction to JavaDoc. A brief summary of the formatting and tags can be found in the reference.

Traditionally, the Java packages in JMRI have used package.html files to contain any needed package-level documentation. It's now recommended that any significant Java package contain a package-info.java file for this. Only a few of these have been included in JMRI so far, and it's not a high priority to replace existing package.html files, but new packages should include a package-info.java copied from java/package-info.java.

A nice discussion of how to use the "deprecated" label in documentation is available on the "How and When To Deprecate APIs" page.

UML and UmlGraph for Developers

UML is a broad and deep language for describing the structure, design and behavior of computing systems. JMRI primarly uses UML class diagrams for documenting its structure. Many UML tutorials are available on the web. In particular, a good starting point is the Object Mentor introduction to class diagrams. For more detail, please see Atlas UML course or Embarcadero Software introduction.

Processing

The standard JMRI Ant build provides three documentation targets:

javadoc

Create the text JavaDocs in the local doc/ directory. Open doc/index.html for access.

javadoc-uml

Create the UML diagrams and JavaDocs in the local doc/ directory. Open doc/index.html for access.

uploadjavadoc

Upload the current documentation in the local doc/ directory to the jmri.org web site. This is done automatically by the CI system, so you generally don't have to deal with it.

Manual Diagrams

---