michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: michael@0: Layout Detailed Design Template michael@0: michael@0: michael@0: michael@0: michael@0:

Gecko Layout Detailed Design Document Template

michael@0: [Use this template to start your detailed design. Replace items in square michael@0: brackets with the appropriate text for your component, class or system.  Keep michael@0: in mind that this is just a general template intended for most designs. michael@0: Your specific design may require different organization or topics - the michael@0: goal is to provide detailed information about the software to the reader.]
michael@0:
michael@0: michael@0:

[Component / Class Name] Detailed Design

michael@0: michael@0:

Overview

michael@0: [Introduce the scope of this design document: what is being documented here. michael@0: Provide a reference back to the High Level design(s) that correspond.]
michael@0: michael@0:
michael@0:

[Class / Component A]

michael@0: [Briefly refresh the reader with the purpose of the class or component. michael@0: Provide enough information to make accessible the following sections on the michael@0: public API, private methods and members, and algorithms. Bring up and tricky michael@0: or otherwise interesting relationships that will be detailed.]
michael@0:
michael@0: michael@0:

Public API

michael@0: [Show the public API for the component, as IDL, C++ header file, or as a michael@0: pseudo-code description.  If using a source file, the comments in the michael@0: source file should cover most of the detail needed. If they do not, then add michael@0: that detail there.  See the Overview document for more details on the michael@0: scope of information that should be presented.]
michael@0: michael@0:

Protected API

michael@0: [If there is a protected API, list the methods and members and indicate michael@0: the responsibilities of the callers with respect o calling the base class, michael@0: enforcing base class invariants, etc.]
michael@0:
michael@0: michael@0:

Implementation Notes

michael@0: [The nasty details of the implementation get exposed here. This section michael@0: can be broken down into subsections as necessary, and should include details michael@0: of particularly important algorithms, performance characteristics or constraints, michael@0: memory usage, tricky ownership issues, and anything else that would make understanding michael@0: the implementation easier for the reader.]
michael@0: michael@0:

Algorithms

michael@0: michael@0:
[Interesting Algorithm 1: The internally maintained sorted list]
michael@0: [explain the nature of the algorithm, the reason it was chosen, the types michael@0: of input it is expected to operate on, etc. Annotated pseudo-code is a good michael@0: idea here, but actual code is often too detailed to b of much use by itself. michael@0: It the actual code is sufficient to understand it, then this subsection is michael@0: probably not needed.]
michael@0: michael@0:
[Interesting Algorithm 2: Handling overflow of the input buffer]
michael@0: [your description here]
michael@0: michael@0:

michael@0: michael@0:
michael@0:

[Class / Component B]

michael@0: [Repeat the structure for the next class or component.]
michael@0:
michael@0: michael@0:
michael@0:

Cross-Component Algorithms

michael@0: [specify the details of algorithms that cross a single component. refer michael@0: to each component, describe the flow of control, the responsibilities of each michael@0: component along the way, the error handling, the state-management if any, michael@0: and the expected results for a given input. Generally each of these algorithms michael@0: gets its own subsection.]
michael@0: michael@0:

[Turning a byte-stream into a fully parsed token-tree]

michael@0: [Detailed description, pesudo-code, state transitions, etc.]
michael@0: michael@0:

[Managing updates to the document]

michael@0: [Detailed description, pesudo-code, state transitions, etc.]
michael@0:
michael@0: michael@0:
michael@0:

Tech Notes

michael@0: [This section contains links to tech notes related to the implementations michael@0: covered in this design.  Tech Notes tend to be extremely specific, often michael@0: recipes for how to do something or how to fix a class of defects.  If michael@0: the tech note is more general, it may be a good idea to move it into the Detailed michael@0: design itself.]
michael@0: michael@0: michael@0:
michael@0: michael@0: michael@0: