diff -r 000000000000 -r 6474c204b198 layout/doc/overview.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/layout/doc/overview.html Wed Dec 31 06:09:35 2014 +0100 @@ -0,0 +1,180 @@ + + + + + + + + Layout Documentation Overview + + + +

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.
+
+ + +