summaryrefslogtreecommitdiffstats
path: root/layout/doc/overview.html
diff options
context:
space:
mode:
Diffstat (limited to 'layout/doc/overview.html')
-rw-r--r--layout/doc/overview.html180
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. &nbsp;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. &nbsp;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>
+ . &nbsp;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). &nbsp;In
+some cases the high level design vocabulary consists of other components
+and not classes. &nbsp;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.
+&nbsp;Missing or invalid links are considered errors in the high-level design.
+ <br>
+ &nbsp;&nbsp; <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. &nbsp;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?) &nbsp;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. &nbsp;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. &nbsp;The extent of this information varies wildly from one
+design to another. &nbsp;Be sure to include an Algorithms section to the
+document when there are interesting or critical algorithms that the classes
+or components employ. &nbsp;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. &nbsp;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. &nbsp;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. &nbsp;Tech
+Notes might contain information about &nbsp;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. &nbsp;The Tech Notes should be stored in a publicly accessible
+location, as a comment or attachment in a bugzilla bug, for example. &nbsp;The
+text that holds the link should be descriptive of what the Tech Note addresses.<br>
+ <br>
+
+ </body>
+ </html>