layout/doc/overview.html

   1 <!-- This Source Code Form is subject to the terms of the Mozilla Public
   2    - License, v. 2.0. If a copy of the MPL was not distributed with this
   3    - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
   4
   5 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   6 <html>
   7 <head>
   8
   9   <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
  10   <title>Layout Documentation Overview</title>
  11 </head>
  12   <body>
  13
  14 <h1>Layout Documentation Overview</h1>
  15 <blockquote> Authors: <br>
  16   <ul>
  17     <li>Marc Attinasi (attinasi@netscape.com)</li>
  18   </ul>
  19 History: <br>
  20   <ul>
  21     <li>12/17/2001 - created<br>
  22     </li>
  23   </ul>
  24  </blockquote>
  25   <h2>Background</h2>
  26  The Layout module of Gecko has not been documented very well. This has lead
  27 to some predictable problems: difficult maintenance, hard to get new people
  28 involved in the module, problems assessing the risk of changes, hard to know
  29 where bugs are likely to be in the source. &nbsp;One extreme result of the
  30 lack of comprehensive has been an urge to rewrite some of the more impenetrable
  31 parts of the layout component, the block and Line Layout areas. &nbsp;Rather
  32 than throwing it all away and rewriting it, we have decided to put significant
  33 effort into thoroughly documenting what we already have. this effort will
  34 help us to understand what parts of the system we want to keep as-is, incrementally
  35 revise, or wholesale rewrite. Additionally, we will make the code base more
  36 accessible to new (and not-so-new) engineers.<br>
  37  <br>
  38
  39   <h2>Strategy:</h2>
  40  Documenting all of Block and Line layout is a large task, so it will be
  41 divided up among knowledgeable and interested engineers. Progress will be
  42 tracked in bugzilla <a href="http://bugzilla.mozilla.org/show_bug.cgi?id=115310">
  43  bug 115310</a>
  44  . &nbsp;This document lays out the basic documentation scope and formatting
  45 so that all of the individual contributions can be combined into a relatively
  46 cohesive unit of linked documents. <br>
  47  <br>
  48
  49   <h2>Scope:</h2>
  50  The documentation will generally cover two levels of detail. There is room
  51 for deviation from this as needed, but generally a High Level Design document
  52 and a Detailed Design document will provide the necessary level of detail
  53 for those trying to understand the system as a whole, and those trying to
  54 get into the code.<br>
  55  <br>
  56
  57   <h3>High Level Designs</h3>
  58  High level designs provided an overview of the system being documented.
  59 The general concept of the component is described, and the classes involved
  60 are described briefly (no details of the class implementations). &nbsp;In
  61 some cases the high level design vocabulary consists of other components
  62 and not classes. &nbsp;The important thing is to describe the interactions
  63 between the classes and/or components such that the reader gets an understanding
  64 of which pieces talk to which other pieces, what kinds of data are shared
  65 by various components or classes, how the data is modified and by whom, beginning
  66 states and end states of a process, and external constraints or inputs into
  67 the system begin described. <br>
  68  <br>
  69  A fundamental piece of the high-level design is the<b> data model</b>. This
  70 is generally a graphical representation of the classes or components involved
  71 in the system, showing the relationships between them in terms of has-a,
  72 is-a, uses, owns, etc. the specific representation is not as important as
  73 the content of the representation. For example, using UML or Booch notation
  74 is fine, as is an ad-hoc diagram that shows the same types of information.<br>
  75  <br>
  76  Another important piece of the high-level design is a set of <b>use-cases</b>
  77   that describe specific interaction that result from specific events in
  78 the system. For example, we might want to show specifically what happens
  79 when an attribute is changed on an element via the DOM. Use cases differ
  80 from data models in that they show specific instances of objects or components,
  81 actual data values where interesting or important, and often give a glimpse
  82 into the algorithms employed. All of the components or objects in the use
  83 cases must be documented in the data model.<br>
  84  <b><br>
  85  State Transition Diagrams</b> may be important to some systems, and they
  86 should be documented in the high-level design as well. These should be described
  87 in terms of the abstract states that the system may be in, not in terms of
  88 how the state-machine is actually implemented.<br>
  89  <br>
  90  The high-level documents provide an overview of the components and classes
  91 that make up a system. It can be used as a road map to the related detailed
  92 design documents for the components and classes involved in the system. thus,
  93 the classes, components, and algorithms referenced in the high-level design
  94 document should be linked to the detailed design documents that correspond.
  95 This link generally occurs at the first reference to the class or component,
  96 but it can be provided in other contexts as well, for convenience to the reader.
  97 &nbsp;Missing or invalid links are considered errors in the high-level design.
  98   <br>
  99  &nbsp;&nbsp; <br>
 100
 101   <h3>Detailed Designs</h3>
 102  Detailed design documents provide specific information needed to implement
 103 (or understand the implementation of) the components and classes described
 104 in the high-level design. Users of the classes or components should also be
 105 able to understand from the detailed design just how the classes, components
 106 and API's are to be used. Special performance characteristics of methods or
 107 interactions should be documented where pertinent.<br>
 108  <br>
 109
 110   <h4>Public API</h4>
 111  The public API of the component or class being documented is essential to
 112 the detailed design. Each publicly accessible interface, method and data member
 113 must be documented. Ideally this information is contained in the implementation
 114 files for a class, interface or component. If this is the case, the actual
 115 IDL or class header file can be used as the documentation for the public API.
 116 This should be done as a link or embedded document to avoid the perpetual
 117 need to keep the document up to date with the source file. &nbsp;Specific
 118 items that are important to the description of the publicly available aspects
 119 of the component, class, or interface include:<br>
 120
 121   <ul>
 122    <li>entry-point semantics: what does the method do, or what does the data
 123 member mean? Is the universe of expected clients limited or open (e.g.. who
 124 can call it)?<br>
 125    </li>
 126    <li>preconditions: what are the legal states for the instance to be in
 127 before the entry point is called? what are the legal values for the arguments?
 128 what are the required states for the objects or components used in the entry-point?</li>
 129    <li>postconditions: what is guaranteed when the entry-point is returned
 130 from? what return values are legal? what is the status of the output arguments
 131 for various return states?</li>
 132    <li>special performance characteristics: if there are special concerns
 133 about performance of the method, explain them. for example, is the method
 134 O(n^2)? Is there considerable memory required? Is the method recursive?</li>
 135
 136   </ul>
 137  Beyond the public interfaces, the private and protected methods need to
 138 be documented as well. For protected methods and members, the expectations
 139 of the subclasses must be made clear (e.g.. should the subclass call the
 140 base class method? if so, when?) &nbsp;As with the public methods, the semantics,
 141 preconditions, postconditions, and special performance considerations should
 142 be described. Again, this may be by direct inclusion of the source code files
 143 where appropriate.<br>
 144  <br>
 145
 146   <h4>Algorithms</h4>
 147  There is often a need to document specific algorithms used in methods and
 148 functions. &nbsp;Generally, it is not a good idea to include this sort of
 149 information in the source files, so they must be described fully in the detailed
 150 design document. &nbsp;The extent of this information varies wildly from one
 151 design to another. &nbsp;Be sure to include an Algorithms section to the
 152 document when there are interesting or critical algorithms that the classes
 153 or components employ. &nbsp;Spell out the algorithms in as much detail as
 154 possible using pseudo-code or diagrams. Ideally, it should be possible to
 155 implement the algorithm from the information in the design.<br>
 156  <br>
 157  <br>
 158  Algorithms that involve several different components or object instances
 159 require special attention. These algorithms tend to be more complex and more
 160 difficult to completely specify. &nbsp;Start out by referring to the related
 161 use cases in the high level design, and then drill down into the responsibilities
 162 and requirements of the individual instances involved. &nbsp;Here, diagrams
 163 and pseudo-code are indispensable in communicating how the algorithm is carried
 164 out across the system.<br>
 165
 166   <h4></h4>
 167   <h4> Tech Notes</h4>
 168 The end of the detailed design document should contain a list of links to
 169 Tech Notes. These will vary in depth and scope, but generally they provide
 170 information geared toward helping developers work on the system. &nbsp;Tech
 171 Notes might contain information about &nbsp;how code has been modified, how
 172 a new feature was added, how to debug a certain class of problem, how to
 173 use built-in debugging r logging facilities, or how to maintain or extend
 174 unit tests. &nbsp;The Tech Notes should be stored in a publicly accessible
 175 location, as a comment or attachment in a bugzilla bug, for example. &nbsp;The
 176 text that holds the link should be descriptive of what the Tech Note addresses.<br>
 177  <br>
 178
 179   </body>
 180   </html>