michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: Layout Documentation Overview michael@0: michael@0: michael@0: michael@0:

Layout Documentation Overview

michael@0:
Authors:
michael@0: michael@0: History:
michael@0: michael@0:
michael@0:

Background

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

Strategy:

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

Scope:

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

High Level Designs

michael@0: High level designs provided an overview of the system being documented. michael@0: The general concept of the component is described, and the classes involved michael@0: are described briefly (no details of the class implementations).  In michael@0: some cases the high level design vocabulary consists of other components michael@0: and not classes.  The important thing is to describe the interactions michael@0: between the classes and/or components such that the reader gets an understanding michael@0: of which pieces talk to which other pieces, what kinds of data are shared michael@0: by various components or classes, how the data is modified and by whom, beginning michael@0: states and end states of a process, and external constraints or inputs into michael@0: the system begin described.
michael@0:
michael@0: A fundamental piece of the high-level design is the data model. This michael@0: is generally a graphical representation of the classes or components involved michael@0: in the system, showing the relationships between them in terms of has-a, michael@0: is-a, uses, owns, etc. the specific representation is not as important as michael@0: the content of the representation. For example, using UML or Booch notation michael@0: is fine, as is an ad-hoc diagram that shows the same types of information.
michael@0:
michael@0: Another important piece of the high-level design is a set of use-cases michael@0: that describe specific interaction that result from specific events in michael@0: the system. For example, we might want to show specifically what happens michael@0: when an attribute is changed on an element via the DOM. Use cases differ michael@0: from data models in that they show specific instances of objects or components, michael@0: actual data values where interesting or important, and often give a glimpse michael@0: into the algorithms employed. All of the components or objects in the use michael@0: cases must be documented in the data model.
michael@0:
michael@0: State Transition Diagrams may be important to some systems, and they michael@0: should be documented in the high-level design as well. These should be described michael@0: in terms of the abstract states that the system may be in, not in terms of michael@0: how the state-machine is actually implemented.
michael@0:
michael@0: The high-level documents provide an overview of the components and classes michael@0: that make up a system. It can be used as a road map to the related detailed michael@0: design documents for the components and classes involved in the system. thus, michael@0: the classes, components, and algorithms referenced in the high-level design michael@0: document should be linked to the detailed design documents that correspond. michael@0: This link generally occurs at the first reference to the class or component, michael@0: but it can be provided in other contexts as well, for convenience to the reader. michael@0:  Missing or invalid links are considered errors in the high-level design. michael@0:
michael@0:   
michael@0: michael@0:

Detailed Designs

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

Public API

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

Algorithms

michael@0: There is often a need to document specific algorithms used in methods and michael@0: functions.  Generally, it is not a good idea to include this sort of michael@0: information in the source files, so they must be described fully in the detailed michael@0: design document.  The extent of this information varies wildly from one michael@0: design to another.  Be sure to include an Algorithms section to the michael@0: document when there are interesting or critical algorithms that the classes michael@0: or components employ.  Spell out the algorithms in as much detail as michael@0: possible using pseudo-code or diagrams. Ideally, it should be possible to michael@0: implement the algorithm from the information in the design.
michael@0:
michael@0:
michael@0: Algorithms that involve several different components or object instances michael@0: require special attention. These algorithms tend to be more complex and more michael@0: difficult to completely specify.  Start out by referring to the related michael@0: use cases in the high level design, and then drill down into the responsibilities michael@0: and requirements of the individual instances involved.  Here, diagrams michael@0: and pseudo-code are indispensable in communicating how the algorithm is carried michael@0: out across the system.
michael@0: michael@0:

michael@0:

Tech Notes

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