181 lines
9.3 KiB
HTML
181 lines
9.3 KiB
HTML
<!-- 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>
|