layout/doc/dd-template.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 Detailed Design Template</title>
  11   <meta name="author" content="Marc Attinasi (attinasi@netscape.com)">
  12 </head>
  13   <body>
  14
  15 <h1><font color="#cc0000">Gecko Layout Detailed Design Document Template</font></h1>
  16    [Use this template to start your detailed design. Replace items in square
  17  brackets with the appropriate text for your component, class or system. &nbsp;Keep
  18  in mind that this is just a general template intended for most designs.
  19 Your  specific design may require different organization or topics - the
  20 goal is  to provide detailed information about the software to the reader.]<br>
  21  <br>
  22
  23 <h1>[Component / Class Name] Detailed Design</h1>
  24
  25 <h2>Overview</h2>
  26  [Introduce the scope of this design document: what is being documented here.
  27 Provide a reference back to the High Level design(s) that correspond.]<br>
  28
  29 <hr width="100%" size="2">
  30 <h2>[Class / Component A]</h2>
  31  [Briefly refresh the reader with the purpose of the class or component.
  32 Provide enough information to make accessible the following sections on the
  33 public API, private methods and members, and algorithms. Bring up and tricky
  34 or otherwise interesting relationships that will be detailed.]<br>
  35  <br>
  36
  37 <h3>Public API</h3>
  38  [Show the public API for the component, as IDL, C++ header file, or as a
  39 pseudo-code description. &nbsp;If using a source file, the comments in the
  40 source file should cover most of the detail needed. If they do not, then add
  41 that detail there. &nbsp;See the Overview document for more details on the
  42 scope of information that should be presented.]<br>
  43
  44 <h3>Protected API</h3>
  45  [If there is a protected API, list the methods and members and indicate
  46 the responsibilities of the callers with respect o calling the base class,
  47 enforcing base class invariants, etc.]<br>
  48  <br>
  49
  50 <h3>Implementation Notes</h3>
  51  [The nasty details of the implementation get exposed here. This section
  52 can be broken down into subsections as necessary, and should include details
  53 of particularly important algorithms, performance characteristics or constraints,
  54 memory usage, tricky ownership issues, and anything else that would make understanding
  55 the implementation easier for the reader.]<br>
  56
  57 <h4>Algorithms</h4>
  58
  59 <h5>[Interesting Algorithm 1: The internally maintained sorted list]</h5>
  60  [explain the nature of the algorithm, the reason it was chosen, the types
  61 of input it is expected to operate on, etc. Annotated pseudo-code is a good
  62 idea here, but actual code is often too detailed to b of much use by itself.
  63 It the actual code is sufficient to understand it, then this subsection is
  64 probably not needed.]<br>
  65
  66 <h5>[Interesting Algorithm 2: Handling overflow of the input buffer]</h5>
  67  [your description here]<br>
  68
  69 <h4></h4>
  70
  71 <hr width="100%" size="2">
  72 <h2>[Class / Component B]</h2>
  73   [Repeat the structure for the next class or component.]<br>
  74  <br>
  75
  76 <hr width="100%" size="2">
  77 <h2>Cross-Component Algorithms</h2>
  78   [specify the details of algorithms that cross a single component. refer
  79 to each component, describe the flow of control, the responsibilities of each
  80 component along the way, the error handling, the state-management if any,
  81 and the expected results for a given input. Generally each of these algorithms
  82 gets its own subsection.]<br>
  83
  84 <h3>[Turning a byte-stream into a fully parsed token-tree]</h3>
  85   [Detailed description, pesudo-code, state transitions, etc.]<br>
  86
  87 <h3>[Managing updates to the document]</h3>
  88   [Detailed description, pesudo-code, state transitions, etc.]<br>
  89  <br>
  90
  91 <hr width="100%" size="2">
  92 <h2>Tech Notes</h2>
  93  [This section contains links to tech notes related to the implementations
  94 covered in this design. &nbsp;Tech Notes tend to be extremely specific, often
  95 recipes for how to do something or how to fix a class of defects. &nbsp;If
  96 the tech note is more general, it may be a good idea to move it into the Detailed
  97 design itself.]<br>
  98
  99 <ul>
 100    <li>[<a href="link%20to%20tech%20note">Debugging buffer overflows</a>
 101  ]</li>
 102    <li>[<a href="link%20to%20tech%20note">Adding new element or attribute
 103 types</a>
 104  ]</li>
 105    <li>[<a href="link%20to%20tech%20note">How To detect and fix problems
 106 with the alignment of elements</a>
 107  ]</li>
 108    <li>[<a href="link%20to%20tech%20note">Fix for Bug 666: ownership of tokens
 109 was mistakenly transferred</a>
 110  ]</li>
 111
 112 </ul>
 113  <br>
 114
 115 </body>
 116 </html>