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