1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/layout/doc/overview.html Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,180 @@
1.4 +<!-- This Source Code Form is subject to the terms of the Mozilla Public
1.5 + - License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
1.7 +
1.8 +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
1.9 +<html>
1.10 +<head>
1.11 +
1.12 + <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
1.13 + <title>Layout Documentation Overview</title>
1.14 +</head>
1.15 + <body>
1.16 +
1.17 +<h1>Layout Documentation Overview</h1>
1.18 +<blockquote> Authors: <br>
1.19 + <ul>
1.20 + <li>Marc Attinasi (attinasi@netscape.com)</li>
1.21 + </ul>
1.22 +History: <br>
1.23 + <ul>
1.24 + <li>12/17/2001 - created<br>
1.25 + </li>
1.26 + </ul>
1.27 + </blockquote>
1.28 + <h2>Background</h2>
1.29 + The Layout module of Gecko has not been documented very well. This has lead
1.30 +to some predictable problems: difficult maintenance, hard to get new people
1.31 +involved in the module, problems assessing the risk of changes, hard to know
1.32 +where bugs are likely to be in the source. One extreme result of the
1.33 +lack of comprehensive has been an urge to rewrite some of the more impenetrable
1.34 +parts of the layout component, the block and Line Layout areas. Rather
1.35 +than throwing it all away and rewriting it, we have decided to put significant
1.36 +effort into thoroughly documenting what we already have. this effort will
1.37 +help us to understand what parts of the system we want to keep as-is, incrementally
1.38 +revise, or wholesale rewrite. Additionally, we will make the code base more
1.39 +accessible to new (and not-so-new) engineers.<br>
1.40 + <br>
1.41 +
1.42 + <h2>Strategy:</h2>
1.43 + Documenting all of Block and Line layout is a large task, so it will be
1.44 +divided up among knowledgeable and interested engineers. Progress will be
1.45 +tracked in bugzilla <a href="http://bugzilla.mozilla.org/show_bug.cgi?id=115310">
1.46 + bug 115310</a>
1.47 + . This document lays out the basic documentation scope and formatting
1.48 +so that all of the individual contributions can be combined into a relatively
1.49 +cohesive unit of linked documents. <br>
1.50 + <br>
1.51 +
1.52 + <h2>Scope:</h2>
1.53 + The documentation will generally cover two levels of detail. There is room
1.54 +for deviation from this as needed, but generally a High Level Design document
1.55 +and a Detailed Design document will provide the necessary level of detail
1.56 +for those trying to understand the system as a whole, and those trying to
1.57 +get into the code.<br>
1.58 + <br>
1.59 +
1.60 + <h3>High Level Designs</h3>
1.61 + High level designs provided an overview of the system being documented.
1.62 +The general concept of the component is described, and the classes involved
1.63 +are described briefly (no details of the class implementations). In
1.64 +some cases the high level design vocabulary consists of other components
1.65 +and not classes. The important thing is to describe the interactions
1.66 +between the classes and/or components such that the reader gets an understanding
1.67 +of which pieces talk to which other pieces, what kinds of data are shared
1.68 +by various components or classes, how the data is modified and by whom, beginning
1.69 +states and end states of a process, and external constraints or inputs into
1.70 +the system begin described. <br>
1.71 + <br>
1.72 + A fundamental piece of the high-level design is the<b> data model</b>. This
1.73 +is generally a graphical representation of the classes or components involved
1.74 +in the system, showing the relationships between them in terms of has-a,
1.75 +is-a, uses, owns, etc. the specific representation is not as important as
1.76 +the content of the representation. For example, using UML or Booch notation
1.77 +is fine, as is an ad-hoc diagram that shows the same types of information.<br>
1.78 + <br>
1.79 + Another important piece of the high-level design is a set of <b>use-cases</b>
1.80 + that describe specific interaction that result from specific events in
1.81 +the system. For example, we might want to show specifically what happens
1.82 +when an attribute is changed on an element via the DOM. Use cases differ
1.83 +from data models in that they show specific instances of objects or components,
1.84 +actual data values where interesting or important, and often give a glimpse
1.85 +into the algorithms employed. All of the components or objects in the use
1.86 +cases must be documented in the data model.<br>
1.87 + <b><br>
1.88 + State Transition Diagrams</b> may be important to some systems, and they
1.89 +should be documented in the high-level design as well. These should be described
1.90 +in terms of the abstract states that the system may be in, not in terms of
1.91 +how the state-machine is actually implemented.<br>
1.92 + <br>
1.93 + The high-level documents provide an overview of the components and classes
1.94 +that make up a system. It can be used as a road map to the related detailed
1.95 +design documents for the components and classes involved in the system. thus,
1.96 +the classes, components, and algorithms referenced in the high-level design
1.97 +document should be linked to the detailed design documents that correspond.
1.98 +This link generally occurs at the first reference to the class or component,
1.99 +but it can be provided in other contexts as well, for convenience to the reader.
1.100 + Missing or invalid links are considered errors in the high-level design.
1.101 + <br>
1.102 + <br>
1.103 +
1.104 + <h3>Detailed Designs</h3>
1.105 + Detailed design documents provide specific information needed to implement
1.106 +(or understand the implementation of) the components and classes described
1.107 +in the high-level design. Users of the classes or components should also be
1.108 +able to understand from the detailed design just how the classes, components
1.109 +and API's are to be used. Special performance characteristics of methods or
1.110 +interactions should be documented where pertinent.<br>
1.111 + <br>
1.112 +
1.113 + <h4>Public API</h4>
1.114 + The public API of the component or class being documented is essential to
1.115 +the detailed design. Each publicly accessible interface, method and data member
1.116 +must be documented. Ideally this information is contained in the implementation
1.117 +files for a class, interface or component. If this is the case, the actual
1.118 +IDL or class header file can be used as the documentation for the public API.
1.119 +This should be done as a link or embedded document to avoid the perpetual
1.120 +need to keep the document up to date with the source file. Specific
1.121 +items that are important to the description of the publicly available aspects
1.122 +of the component, class, or interface include:<br>
1.123 +
1.124 + <ul>
1.125 + <li>entry-point semantics: what does the method do, or what does the data
1.126 +member mean? Is the universe of expected clients limited or open (e.g.. who
1.127 +can call it)?<br>
1.128 + </li>
1.129 + <li>preconditions: what are the legal states for the instance to be in
1.130 +before the entry point is called? what are the legal values for the arguments?
1.131 +what are the required states for the objects or components used in the entry-point?</li>
1.132 + <li>postconditions: what is guaranteed when the entry-point is returned
1.133 +from? what return values are legal? what is the status of the output arguments
1.134 +for various return states?</li>
1.135 + <li>special performance characteristics: if there are special concerns
1.136 +about performance of the method, explain them. for example, is the method
1.137 +O(n^2)? Is there considerable memory required? Is the method recursive?</li>
1.138 +
1.139 + </ul>
1.140 + Beyond the public interfaces, the private and protected methods need to
1.141 +be documented as well. For protected methods and members, the expectations
1.142 +of the subclasses must be made clear (e.g.. should the subclass call the
1.143 +base class method? if so, when?) As with the public methods, the semantics,
1.144 +preconditions, postconditions, and special performance considerations should
1.145 +be described. Again, this may be by direct inclusion of the source code files
1.146 +where appropriate.<br>
1.147 + <br>
1.148 +
1.149 + <h4>Algorithms</h4>
1.150 + There is often a need to document specific algorithms used in methods and
1.151 +functions. Generally, it is not a good idea to include this sort of
1.152 +information in the source files, so they must be described fully in the detailed
1.153 +design document. The extent of this information varies wildly from one
1.154 +design to another. Be sure to include an Algorithms section to the
1.155 +document when there are interesting or critical algorithms that the classes
1.156 +or components employ. Spell out the algorithms in as much detail as
1.157 +possible using pseudo-code or diagrams. Ideally, it should be possible to
1.158 +implement the algorithm from the information in the design.<br>
1.159 + <br>
1.160 + <br>
1.161 + Algorithms that involve several different components or object instances
1.162 +require special attention. These algorithms tend to be more complex and more
1.163 +difficult to completely specify. Start out by referring to the related
1.164 +use cases in the high level design, and then drill down into the responsibilities
1.165 +and requirements of the individual instances involved. Here, diagrams
1.166 +and pseudo-code are indispensable in communicating how the algorithm is carried
1.167 +out across the system.<br>
1.168 +
1.169 + <h4></h4>
1.170 + <h4> Tech Notes</h4>
1.171 +The end of the detailed design document should contain a list of links to
1.172 +Tech Notes. These will vary in depth and scope, but generally they provide
1.173 +information geared toward helping developers work on the system. Tech
1.174 +Notes might contain information about how code has been modified, how
1.175 +a new feature was added, how to debug a certain class of problem, how to
1.176 +use built-in debugging r logging facilities, or how to maintain or extend
1.177 +unit tests. The Tech Notes should be stored in a publicly accessible
1.178 +location, as a comment or attachment in a bugzilla bug, for example. The
1.179 +text that holds the link should be descriptive of what the Tech Note addresses.<br>
1.180 + <br>
1.181 +
1.182 + </body>
1.183 + </html>
