diff options
Diffstat (limited to 'layout/doc/overview.html')
| -rw-r--r-- | layout/doc/overview.html | 180 |
1 files changed, 180 insertions, 0 deletions
diff --git a/layout/doc/overview.html b/layout/doc/overview.html new file mode 100644 index 000000000..93ff4891b --- /dev/null +++ b/layout/doc/overview.html @@ -0,0 +1,180 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> + +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> + + <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1"> + <title>Layout Documentation Overview</title> +</head> + <body> + +<h1>Layout Documentation Overview</h1> +<blockquote> Authors: <br> + <ul> + <li>Marc Attinasi (attinasi@netscape.com)</li> + </ul> +History: <br> + <ul> + <li>12/17/2001 - created<br> + </li> + </ul> + </blockquote> + <h2>Background</h2> + 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.<br> + <br> + + <h2>Strategy:</h2> + 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 <a href="http://bugzilla.mozilla.org/show_bug.cgi?id=115310"> + bug 115310</a> + . 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. <br> + <br> + + <h2>Scope:</h2> + 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.<br> + <br> + + <h3>High Level Designs</h3> + 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. <br> + <br> + A fundamental piece of the high-level design is the<b> data model</b>. 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.<br> + <br> + Another important piece of the high-level design is a set of <b>use-cases</b> + 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.<br> + <b><br> + State Transition Diagrams</b> 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.<br> + <br> + 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. + <br> + <br> + + <h3>Detailed Designs</h3> + 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.<br> + <br> + + <h4>Public API</h4> + 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:<br> + + <ul> + <li>entry-point semantics: what does the method do, or what does the data +member mean? Is the universe of expected clients limited or open (e.g.. who +can call it)?<br> + </li> + <li>preconditions: what are the legal states for the instance to be in +before the entry point is called? what are the legal values for the arguments? +what are the required states for the objects or components used in the entry-point?</li> + <li>postconditions: what is guaranteed when the entry-point is returned +from? what return values are legal? what is the status of the output arguments +for various return states?</li> + <li>special performance characteristics: if there are special concerns +about performance of the method, explain them. for example, is the method +O(n^2)? Is there considerable memory required? Is the method recursive?</li> + + </ul> + 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.<br> + <br> + + <h4>Algorithms</h4> + 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.<br> + <br> + <br> + 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.<br> + + <h4></h4> + <h4> Tech Notes</h4> +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.<br> + <br> + + </body> + </html> |