Introduction

Documentation guidelines are needed so that quality of guidance and fact remains consistent across this project. This level of quality is expected of all Confluence users. The guidelines to follow are written here to provide instruction for anyone involved in the development or use of the CAS4 (pending) release. These guidelines are written specifically for the text found under this Confluence hosting.

Please note that some excerpts of the guidelines found here were taken from the author Doug Lea, concurrent programming expert and are considered public domain.

Documentation Guidelines

This release will be developed by a virtual team. This team will rely on the information found here to do its job. Again, it is up to the Confluence users here to see that everything is documented clearly and with quality. Our communication will set the measure for our success. Various areas of the project that require documentation are found below. Also, it should be important to note that two levels of documentation will exist for this project, MUST document and SHOULD document. This distinction will be addressed in the various sections.

Source Documentation

(MUST document) All code including Java, HTML, XML, XSLT, etc. should be clearly documented following the standards for that development language. I.e. Java Docs for Java. Documentation for the code should be place in a publicly accessible location and be maintained for all actively developed and maintained branches of the code base.

Javadoc is important because it can be used with Maven to generate a well-documented frameset of all CAS packages and source code. The report is solely dependent on your use of javadoc comments. Development process shall remain loose, however coding standards assure quality in the work that we produce.

Specific File Documentation

Begin each Java file with a comment including appropriately dated copyright notice:

Example:

/*
 * Copyright 2007 The JA-SIG Collaborative. All rights reserved. See license
 * distributed with this file and available online at
 * http://www.uportal.org/license.html
 */
package org.jasig.cas.services;

Please note that the above copyright is shown above for example formatting only.

Classes and Interfaces

Write all /** ... */ comments using javadoc conventions. (Even though not required by javadoc, end each /* comment with **/ to make it easier to read and check.)

Preface each class with a /** ... **/ comment describing the purpose of the class, guaranteed invariants, usage instructions, and/or usage examples. Also include any reminders or disclaimers about required or desired improvements. Use HTML format, with added tags:

• @author author-name
• @version version number of class
• @see string
• @see URL
• @see classname#methodname

Example:

/**
 * A class representing a security principal
 * For example:
 * <pre>
 * 	CartoonPrincipal subject = new CartoonPrincipal();
 *	subject.setUsername("popeye");
 * </pre>
 *
 * @see		javax.security.Principal
 * @version	1.0 31 Aug 2008
 * @author 	rlewis
**/
class CartoonPrincipal extends Principal {


	...
}

Class Variables

Use javadoc conventions to describe nature, purpose, constraints, and usage of instances variables and static variables. Use HTML format, with added tags:

• @see string
• @see URL
• @see classname#methodname

Example:

    /**
     * The current number of elements.
     * must be non-negative, and less than or equal to capacity.
    **/
    protected int count_;

Methods

Use javadoc conventions to describe nature, purpose, preconditions, effects, algorithmic notes, usage instructions, reminders, etc. Use HTML format, with added tags:

• @param paramName description. (Note: In alpha versions of Java, this is listed as @arg, not @param.)
• @return description of return value
• @exception exceptionName description
• @see string
• @see URL
• @see classname#methodname

Be as precise as reasonably possible in documenting effects. Here are some conventions and practices for semi-formal specifications.

@return condition: (condition)
describes postconditions and effects true upon return of a method.
@exception exceptionName IF (condition)
indicates the conditions under which each exception can be thrown. Include conditions under which uncommon unchecked (undeclared) exceptions can be thrown.
@param paramname WHERE (condition)
indicates restrictions on argument values. Alternatively, if so implemented, list restrictions alongside the resulting exceptions, for example IllegalArgumentException. In particular, indicate whether reference arguments are allowed to be null.
WHEN (condition)
indicates that actions use guarded waits until the condition holds.
RELY (condition)
describes assumptions about execution context. In particular, relying on other actions in other threads to terminate or provide notifications.
GENERATE T
to describe new entities (for the main example, Threads) constructed in the course of the method.
ATOMIC
indicates whether actions are guaranteed to be uninterfered with by actions in other threads (normally as implemented via synchronized methods or blocks).
PREV(obj)
refers to the state of an object at the onset of a method.
OUT(message)
describes messages (including notifications such as notifyAll) that are sent to other objects as required aspects of functionality, or referrred to in describing the effects of other methods.
foreach (int i in lo .. hi) predicate
means that predicate holds for each value of i.
foreach (Object x in e) predicate
means that the predicate holds for each element of a collection or enumeration.
foreach (Type x) predicate
means that the predicate holds for each instance of Type.
-->
means `implies'.
unique
means that the value is different than any other. For example, a unique instance variable that always refers to an object that is not referenced by any other object.
fixed
means that the value is never changed after it is initialized.

Example:

  /**
   * Insert element at front of the sequence
   *     
   * @param element the element to add
   * @return condition:
   * <PRE>
   *  size() == PREV(this).size()+1 &&
   *  at(0).equals(element) &&
   *  foreach (int i in 1..size()-1) at(i).equals(PREV(this).at(i-1)) 
   * </PRE>
  **/

  public void        addFirst(Object element);

Local declarations, statements, and expressions

Use /* ... */ comments to describe algorithmic details, notes, and related documentation that spans more than a few code statements.

Example:

    /*
     * Strategy:
     *    1. Find the node
     *    2. Clone it
     *    3. Ask inserter to add clone 
     *    4. If successful, delete node
     */

Use Running // comments to clarify non-obvious code. But don't bother adding such comments to obvious code; instead try to make code obvious!

Example:

int index = -1; // -1 serves as flag meaning the index isn't valid

Or, often better:

static final int INVALID= -1; 
int index = INVALID;

Coding standards not related to source documentation can be found here

Feature or Use-Case Documentation

High level CAS features should be conceptualized or abstracted into specific use-case scenario components. Fine-grained features can be extracted and detailed as separate tasks in JIRA.

JIRA, an enterprise bug tracking tool will be used to manage specific tasks and later bugs. JIRA can provide documentation of specific tasks, however it is not the best tool for overall understanding. Conveyance of this overall understanding is up to the developers of the CAS release. This documentation should reside within the boundaries of the Confluence space.

Each CAS developer should begin thinking about how we convey system design to each other outside of the guidelines found here. E.g. do we need to all use ArgoUML or as a group are we comfortable with source and stub methods. Some people prefer conference calls and a whiteboard. Each of us should think about this and prepare for discussion. All methods work but one method needs to work for us. Feel free to comment here below.

Knowledgebase

(SHOULD document) Anything we learn from the exercise of this project should be documented in this Confluence space. Just the change in team size will bring a few issues that we will have to resolve as they come about. Our lessons learned need to be documented in a manner where everyone understands them too. CAS is complicated in and of itself, however better documentation helps understanding, development, testing, implementation, and use overall.

Our knowledge base belongs to all. But, we will post it and organize its content here. We will probably structure the documentation for the project using the same outline found here.

Other Documentation

Some will do and some will ask. If you ask for or need documentation and can't find it, either add a link for the creation of a new page or create one yourself. If you are uncomfortable doing this, let another team member know and someone can at least outline the document needed. Don't be shy. The pyramids got built by the hands of many, many people. This is no different.

Confluence belongs to us (developers) first. We'll fix any grammar or formatting issues before the general public shows up. I say that as a warning. The public will come here. That's why we should leave a trail of quality. If we document something we're adding value to our CAS product. We're leaving things better than when we came.