Layout Documentation Overview

Authors:
History:

Background

The Layout module of Gecko has not been documented very well. This has lead to some predictable problems: difficult maintenance, hard to get new people involved in the module, problems assessing the risk of changes, hard to know where bugs are likely to be in the source.  One extreme result of the lack of comprehensive has been an urge to rewrite some of the more impenetrable parts of the layout component, the block and Line Layout areas.  Rather than throwing it all away and rewriting it, we have decided to put significant effort into thoroughly documenting what we already have. this effort will help us to understand what parts of the system we want to keep as-is, incrementally revise, or wholesale rewrite. Additionally, we will make the code base more accessible to new (and not-so-new) engineers.

Strategy:

Documenting all of Block and Line layout is a large task, so it will be divided up among knowledgeable and interested engineers. Progress will be tracked in bugzilla bug 115310 .  This document lays out the basic documentation scope and formatting so that all of the individual contributions can be combined into a relatively cohesive unit of linked documents.

Scope:

The documentation will generally cover two levels of detail. There is room for deviation from this as needed, but generally a High Level Design document and a Detailed Design document will provide the necessary level of detail for those trying to understand the system as a whole, and those trying to get into the code.

High Level Designs

High level designs provided an overview of the system being documented. The general concept of the component is described, and the classes involved are described briefly (no details of the class implementations).  In some cases the high level design vocabulary consists of other components and not classes.  The important thing is to describe the interactions between the classes and/or components such that the reader gets an understanding of which pieces talk to which other pieces, what kinds of data are shared by various components or classes, how the data is modified and by whom, beginning states and end states of a process, and external constraints or inputs into the system begin described.

A fundamental piece of the high-level design is the data model. This is generally a graphical representation of the classes or components involved in the system, showing the relationships between them in terms of has-a, is-a, uses, owns, etc. the specific representation is not as important as the content of the representation. For example, using UML or Booch notation is fine, as is an ad-hoc diagram that shows the same types of information.

Another important piece of the high-level design is a set of use-cases that describe specific interaction that result from specific events in the system. For example, we might want to show specifically what happens when an attribute is changed on an element via the DOM. Use cases differ from data models in that they show specific instances of objects or components, actual data values where interesting or important, and often give a glimpse into the algorithms employed. All of the components or objects in the use cases must be documented in the data model.

State Transition Diagrams may be important to some systems, and they should be documented in the high-level design as well. These should be described in terms of the abstract states that the system may be in, not in terms of how the state-machine is actually implemented.

The high-level documents provide an overview of the components and classes that make up a system. It can be used as a road map to the related detailed design documents for the components and classes involved in the system. thus, the classes, components, and algorithms referenced in the high-level design document should be linked to the detailed design documents that correspond. This link generally occurs at the first reference to the class or component, but it can be provided in other contexts as well, for convenience to the reader.  Missing or invalid links are considered errors in the high-level design.
  

Detailed Designs

Detailed design documents provide specific information needed to implement (or understand the implementation of) the components and classes described in the high-level design. Users of the classes or components should also be able to understand from the detailed design just how the classes, components and API's are to be used. Special performance characteristics of methods or interactions should be documented where pertinent.

Public API

The public API of the component or class being documented is essential to the detailed design. Each publicly accessible interface, method and data member must be documented. Ideally this information is contained in the implementation files for a class, interface or component. If this is the case, the actual IDL or class header file can be used as the documentation for the public API. This should be done as a link or embedded document to avoid the perpetual need to keep the document up to date with the source file.  Specific items that are important to the description of the publicly available aspects of the component, class, or interface include:
Beyond the public interfaces, the private and protected methods need to be documented as well. For protected methods and members, the expectations of the subclasses must be made clear (e.g.. should the subclass call the base class method? if so, when?)  As with the public methods, the semantics, preconditions, postconditions, and special performance considerations should be described. Again, this may be by direct inclusion of the source code files where appropriate.

Algorithms

There is often a need to document specific algorithms used in methods and functions.  Generally, it is not a good idea to include this sort of information in the source files, so they must be described fully in the detailed design document.  The extent of this information varies wildly from one design to another.  Be sure to include an Algorithms section to the document when there are interesting or critical algorithms that the classes or components employ.  Spell out the algorithms in as much detail as possible using pseudo-code or diagrams. Ideally, it should be possible to implement the algorithm from the information in the design.


Algorithms that involve several different components or object instances require special attention. These algorithms tend to be more complex and more difficult to completely specify.  Start out by referring to the related use cases in the high level design, and then drill down into the responsibilities and requirements of the individual instances involved.  Here, diagrams and pseudo-code are indispensable in communicating how the algorithm is carried out across the system.

Tech Notes

The end of the detailed design document should contain a list of links to Tech Notes. These will vary in depth and scope, but generally they provide information geared toward helping developers work on the system.  Tech Notes might contain information about  how code has been modified, how a new feature was added, how to debug a certain class of problem, how to use built-in debugging r logging facilities, or how to maintain or extend unit tests.  The Tech Notes should be stored in a publicly accessible location, as a comment or attachment in a bugzilla bug, for example.  The text that holds the link should be descriptive of what the Tech Note addresses.