The Tor Browser / file comparison
comparison: layout/doc/overview.html
layout/doc/overview.html
- branch
- TOR_BUG_9701
- changeset 11
- deefc01c0e14
equal
deleted
inserted
replaced
| -1:000000000000 | 0:e02c2616e387 |
|---|---|
| 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. 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. 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 . 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). In | |
| 61 some cases the high level design vocabulary consists of other components | |
| 62 and not classes. 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 Missing or invalid links are considered errors in the high-level design. | |
| 98 <br> | |
| 99 <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. 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?) 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. 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. The extent of this information varies wildly from one | |
| 151 design to another. 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. 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. 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. 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. Tech | |
| 171 Notes might contain information about 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. The Tech Notes should be stored in a publicly accessible | |
| 175 location, as a comment or attachment in a bugzilla bug, for example. The | |
| 176 text that holds the link should be descriptive of what the Tech Note addresses.<br> | |
| 177 <br> | |
| 178 | |
| 179 </body> | |
| 180 </html> |
