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