layout/doc/dd-template.html

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