Magic-Mirror/gecko-dev
1
0
Fork 0
mirror of https://github.com/mozilla/gecko-dev.git synced 2024-11-25 13:51:41 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

New layout documents: templates and space manager documentation. See bug 115310 and join in the fun

Browse Source
This commit is contained in:
attinasi%netscape.com 2002-01-16 01:06:26 +00:00
parent 516c9ddece
commit 3e780ab9d9
8 changed files with 945 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

279
layout/doc/DD-SpaceManager.html Normal file
View File

File diff suppressed because one or more lines are too long

BIN
layout/doc/ExampleClassDiagram.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.5 KiB

238
layout/doc/HLD-SpaceManager.html Normal file
View File

@ -0,0 +1,238 @@
<!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>Space Manager High Level Design</title>
<meta name="author" content="Marc Attinasi (attinasi@netscape.com)">
</head>
<body>
<h1><font color="#cc0000">Gecko Layout High Level Design Document</font></h1>
<h1>Space Manager High Level Design</h1>
<br>
<h2>Overview</h2>
The Space Manager and associated classes and strructures are used by Block
and Line layout to manage rectangular regions that are occupied and available,
for correct handling of floated elements and the elements that flow around
them. &nbsp;When elements are floated to the left or right in a layout, they
take up space and influence where other elements can be placed. &nbsp;The
Space Manager is responsible for keeping track of where space is taken up
and where it is available. This information is used by block layout to correctly
compute where other floated elements should be placed, and how much space
is available to normal in-flow elements that flow around the floated bits.<br>
<br>
The Space Manager works in concert with several other classes to do its
job. The classes that are considered part of the Space Manager are:<br>
<ul>
<li>nsSpaceManager</li>
<li>nsBandData</li>
<li>nsBlockBandData</li>
<li>BandRect / BandList (private structs)</li>
<li>FrameInfo (private struct)</li>
<li>nsBandtrapezoid</li>
</ul>
Outside of the Space Manager itself, the clients of the Space Manager also
play an inportant part in the management of he available and used space.
&nbsp;The primary classes that interact witht eh Space Manager are:<br>
<ul>
<li>nsBlockReflowState</li>
<li>nsBlockFrame</li>
<li>nsBoxToBlockAdaptor</li>
</ul>
The general interaction model is to create a Space Manager for a block
frame in the context of a Reflow, and to associate it with the BlockReflowState
so it is passed down to child frames' reflow methods. After reflow, the
Space Manager is destroyed. &nbsp;During reflow, the space manager stores
the space taken up by floaters (UpdateSpaceManager in nsBlockFrame) and
provides information about the space available for other elements (GetAvailableSpace
in nsBlockReflowState). &nbsp;<br>
<br>
Additionally, there is a need to manage impacts to lines caused by changes
to floated elements. &nbsp;This is referred to as Propagation of Floater Damage
and is handled by the Block Frame, making use of teh Space Manager. When
dirty lines are incrementally reflowed, the Space Manger is told about the
larger of the new or old line combined width, which it records in an internal
nsIntervalSet as potential floater damage (the method is IncludeInDamage).
During the incremental reflow of dirty lines the block frame may encounter
lines that are NOT dirty. In this case the Space Manager is also asked if
&nbsp;there is any floater damage, and if there is then the block further
checks to see if that damage intersects the area of the non-dirty line, marking
it dirty if there is intersection. &nbsp;Thus, changes to floaters on other
lines may cause impact to otherwise clean lines, and the Space Manager facilitates
the detection of this.
<h2>Data Model</h2>
<h4>Class/Component Diagram</h4>
<blockquote>
<div align="Left"><img src="SpaceManagerClasses.gif" alt="SpaceManager Class Diagram" width="500" height="459" title="Example Class Diagram">
<br>
</div>
</blockquote>
<ul>
<li>nsSpaceManager: The central point of management of the space taken
up by floaters in a block</li>
<li>nsBandData: Provides information about the frames occupying a band
of occupied or available space</li>
<li>nsBlockBandData: A specialization of nsBandData that is used by
nsBlockReflowState to determine the available space, floater impacts, and
where floaters are cleared. &nbsp;Essentially a CSS-specific wrapper for
generic nsBandData.</li>
<li>BandRect: Keeps the bounds of a band, along with the frames associated
with the band. &nbsp;BandRects are a linked list (provided by PRCListStr
super-class) and also provide some geometry-management methods (SplitVertically,
SplitHorizontally) and some methods that query or manipulate the frames associated
with the band (IsOccupiedBy, AddFrame, RemoveFrame).</li>
<li>BandList: A subclass of BandRect that provides a list interface
- Head(), Tail(), IsEmpty(), etc.</li>
<li>FrameInfo: A structure that keeps information about the rectangle
associated with a specific frame, in a linked list.</li>
<li>nsBandTrapezoid: Represents the discrete regions within a band that
are either Available, Occupied by a single frame, or Occupied by several
frames. &nbsp;This is used to communicate information about the space in
the band to the clients of the SpaceManager. &nbsp;There is no internal use
of the nsBandTrapezoid by the Space Manager, rather it uses its internal
BandList to create a BandData collection, which is largely made up of nsTrapezoid
data.<br>
</li>
</ul>
<h2>Use Case</h2>
<h4>Use Case 1: Space Manger is Created / Destroyed</h4>
Space Manager instances are created in the nsBlockFrame's Reflow method.
&nbsp;<br>
<ul>
<li>An instance is created&nbsp;</li>
<li>The BlockReflowState's previous Space Manger is saved off.</li>
<li>The new Space Manger instance is associated with the BlockReflowState.
&nbsp;</li>
<li>After the block frame's Reflow has completed, the old Space Manager
instance is re-associated with the BlockReflowState</li>
<li>The new Space Manager is destroyed.</li>
</ul>
If the BlockReflowState already had a Space Manager instance associated
with it, it is stored off before being replaced, and the returned to the
BlockReflowState instance after the new one has been destroyed. &nbsp;Thus,
Space Managers are effectively 'nested' during reflow, with each new block
introducing its own Space Manager.
<h4>Use Case 2: Floater is added to the Space Manager</h4>
After a Space Manager is created for a block context's reflow chain, a
floated block may be added to it. &nbsp;This happens via the nsBlockFrame
method UpdateSpaceManager. &nbsp;The general algorightm is:<br>
<ul>
<li>For each line in the block, see if it has floated blocks</li>
<li>If floaters are in the line, iterate over the floaters and add each
one to the Space Manger via the AddRectRegion method. &nbsp;The actual rect
for the frame is cached in an nsFloaterCache so it does nto have to be recomputed.</li>
<li>If the block has any block children, then translate the Space Manager
to the child block's origin and update the space manager in the context
fo the child block, recursively. When done with the child, restore the Space
Managers coordinates by translating by the negative of the child block's
origin.&nbsp; <br>
</li>
</ul>
<h4>Use Case 3: Space Manager is used to find available space to reflow
into</h4>
The nsBlockFrame makes use of the Space Manager indirectly to get the available
space to reflow a child block or inline frame into. The block frame uses
a helper method on the nsBlockReflowState class to do the actual computation
of available space based on the data in the Space Manger. Here is how it
works for reflowing an inline frame within a block (this also occurs for
reflowing a block frame and, partially, for preparing for a resize reflow).<br>
<ul>
<li>nsBlockFrame first frees all floater information for the line that
is being reflowed.</li>
<li>GetAvailableSpace is called on the BlockReflowState</li>
<li>the BlockReflowState calls GetAvailableSpace on its BlockBandData
instance (which was setup in the BlockReflowState's constructor based on
the SpaceManager passed in and computed content area).</li>
<li>BlockBandData then gets the band data from the space manager via
a call to the Space Manager associated with the BlockBandData instance.</li>
<li>The BlockBandData then walks the collection of trapezoids that were
returned by the SpaceManager method GetBandData (as nsBandData wrappers)
and determines the right-most edge of the available space.</li>
<li>The BlockReflowState then stores this available space rect for use
in the rest of the reflow chain.<br>
</li>
</ul>
<h4>Use Case 4: Propagation of Floater Damage: remembering floater damage</h4>
This process is driven by the Block Frame.<br>
<ul>
<li>A dirty line is reflowed</li>
<li>If the line's combined area has changed then the Space Manager is
told to include the combined area as a floater damage interval.</li>
</ul>
<h4>Use Case 5: Propagation of Floater Damage: detecting and handling floater
damage</h4>
This process is driven by the Block Frame.<br>
<ul>
<li>A non-dirty line is encountered by the Block Frame in ReflowDirtyLines</li>
<li>Block Frame calls its PropagateFloaterDamage method</li>
<li>The Space Manger is checked to see if ther is any floater damage</li>
<li>If there is, then the block frame asks the Space Manager if the
line in question intersects the floater damage</li>
<li>If the line does intersect a damage interval, then the line is marked
dirty</li>
<li>If the line does not intersect a damage interval, it may still be
marked dirty if:</li>
<ul>
<li>it was impacted by floaters before, but is not any longer</li>
<li>it was not impacted by floaters befre, but is now</li>
<li><a name="block-line-impact"></a>
it is impacted by floaters and is a block<br>
</li>
</ul>
</ul>
<br>
<hr width="100%" size="2"><br>
<h1><font color="#ff0000">Problems / bugs found during documentation:</font></h1>
<ul>
<li>BandRect and BandList are public in nsSpaceManager.h - should be
private (compiles fine)</li>
<li>nsSpaceManager data members are declared protected, but there are
no subclasses. Should be private (compiles fine)</li>
<li>nsBlockFrame::Paint is mucking with nsBlockBandData in and #if 0
block - remove that and the include (compiles fine)</li>
<li>nsSpaceManger has no way of clearing the floater damage interval
set - this might be needed if the SpaceManager persists beyond a Reflow</li>
<li>As dbaron has documetned inteh code, the floater damage logic is
flawed: it only handles vertical changes to a line's combined area. &nbsp;The
Floater Damage API on the Space Manger does not support horizontal changes,
and the block frame does not attempt to handle them either except for the
case of a <a href="#block-line-impact">block-line impacted by a floater</a>
.</li>
</ul>
<br>
<br>
</body>
</html>

BIN
layout/doc/SpaceManagerClasses.gif Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

112
layout/doc/dd-template.html Normal file
View File

@ -0,0 +1,112 @@
<!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 is 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 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>

105
layout/doc/hld-template.html Normal file
View File

@ -0,0 +1,105 @@
<!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 High Level design Template</title>
<meta name="author" content="Marc Attinasi (attinasi@netscape.com)">
</head>
<body>
<h1><font color="#cc0000">Gecko Layout High Level Design Document Template</font></h1>
[Use this template to start your high level 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 high-level information about the software to the reader.]<br>
<br>
<h1>[Component/Class/System Name] High Level Design</h1>
<br>
<h2>Overview</h2>
[Provide a descriptive overview of the component, class, or system that
you are documenting. Describe what the system is supposed to do, where it
is in the overall system, who the clients are, how it is expected to perform,
and any other information that is important to convey to somebody interested
in understanding what the documented system is all about.]<br>
<br>
<h2>Data Model</h2>
[This section describes the classes or components that make up the data
model for the system being documented. It can include a graphical representation
of the classes and their relationships to each other (derivation, aggregation,
ownership, usership, etc.). No implementation details are to be included
here, but general relationships and inter-relationships should be shown and
briefly described. The reader should be able to understand the players in
the system, and the extent to which those players interact with or are related
to the other players.]<br>
<h4>Class/Component Diagram</h4>
<blockquote>
<div align="Left"><img src="ExampleClassDiagram.jpg" alt="Example Class Diagram" width="324" height="270" title="Example Class Diagram">
<br>
</div>
</blockquote>
<ul>
<li>[Class/<a href="Link%20To%20Component%20A%20Detailed%20Design">
Component A</a>
]: This class is used to...</li>
<li>[Class/<a href="Link%20To%20Component%20B%20Detailed%20Design">
Component B</a>
]: This class works with Class A to...<br>
</li>
</ul>
<br>
<h2>Use Case</h2>
[Use Cases describe interactions between specific instances of the objects
or components described in the Data Model. &nbsp;There will generally be
use cases for each &nbsp; interesting runtime interaction between the objects
in the system. An extremely simple system will have at least one use case
describing the behavior of the simple system in action, but most systems
have many use cases corresponding to the any things that the system does.
&nbsp;The reader should be able to find the use case (or cases) that correspond
to the situation they are interested in understanding, and they should be
able to learn how data flows through the system, what objects are involved,
how &nbsp;object and data life-cycles are managed (e.g. where allocations
ad deallocations occur, and who maintains ownership). This section makes up
the bulk of the document. It touches on implementations and algorithms, but
rather than describing them in detail, it stays high-level and links to the
detailed designs that correspond.]<br>
<h4>[Use Case 1: Component is Created]</h4>
The component is created by a client with...<br>
&nbsp;[Image could go here if it were interesting enough...]<br>
<br>
<h4>[Use Case 2: Component is Destroyed]</h4>
When the client is finished with the instance they created (or were given
ownership of) the destroy it by calling...<br>
<br>
<h4>[Use Case 3: Component is used to find all invalid links on the page]</h4>
Descriptive text of how the component is invoked goes here. The other
components that it uses to carry out its task are shown, and the general
flow of data is documented.<br>
[Picture of the component instance with annotations showing data flow,
ownership, etc. goes here]<br>
<h2>State Transitions</h2>
[Where appropriate, the discrete states of a system should be enumerated
and the transitions between the states defined. &nbsp;Not all systems require
full state transition diagrams, but most systems have at least a handful
of interesting states, and at least a small number of interesting stimuli
that cause transitions from one state to another. &nbsp; Of course, classes
or components that are not stateful have no need for this section.]<br>
<br>
<br>
</body>
</html>

35
layout/doc/index.html Normal file
View File

@ -0,0 +1,35 @@
<!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>Gecko Layout Documentation Index</title>
</head>
<body>
<h1>Gecko Layout Documentation</h1>
<br>
<h2>Meta Documents:</h2>
<ul>
<li><a href="overview.html">Documentation Overview</a>
</li>
<li><a href="hld-template.html">High Level Design Document Template</a>
</li>
<li><a href="dd-template.html">Detailed Design Document Template</a>
<br>
</li>
</ul>
<h2>Completed Documents:</h2>
<ul>
<li>Space Manger: <a href="HLD-SpaceManager.html">High Level Design</a>
&nbsp;- &nbsp;<a href="DD-SpaceManager.html">Detailed Design</a>
</li>
<li><br>
</li>
</ul>
<h2>Works in Progress:</h2>
<ul>
<li>Debugging Facilities (Bernd): <br>
</li>
</ul>
<br>
</body>
</html>

176
layout/doc/overview.html Normal file
View File

@ -0,0 +1,176 @@
<!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 Documentation Overview</title>
</head>
<body>
<h1>Layout Documentation Overview</h1>
<blockquote> Authors: <br>
<ul>
<li>Marc Attinasi (attinasi@netscape.com)</li>
</ul>
History: <br>
<ul>
<li>12/17/2001 - created<br>
</li>
</ul>
</blockquote>
<h2>Background</h2>
The Layout module of Gecko has not been documented very well. This has lead
to some predictable problems: difficult maintenance, hard to get new people
involved in the module, problems assessing the risk of changes, hard to know
where bugs are likely to be in the source. &nbsp;One extreme result of the
lack of comprehensive has been an urge to rewrite some of the more impenetrable
parts of the layout component, the block and Line Layout areas. &nbsp;Rather
than throwing it all away and rewriting it, we have decided to put significant
effort into thoroughly documenting what we already have. this effort will
help us to understand what parts of the system we want to keep as-is, incrementally
revise, or wholesale rewrite. Additionally, we will make the code base more
accessible to new (and not-so-new) engineers.<br>
<br>
<h2>Strategy:</h2>
Documenting all of Block and Line layout is a large task, so it will be
divided up among knowledgeable and interested engineers. Progress will be
tracked in bugzilla <a href="http://bugzilla.mozilla.org/show_bug.cgi?id=115310">
bug 115310</a>
. &nbsp;This document lays out the basic documentation scope and formatting
so that all of the individual contributions can be combined into a relatively
cohesive unit of linked documents. <br>
<br>
<h2>Scope:</h2>
The documentation will generally cover two levels of detail. There is room
for deviation from this as needed, but generally a High Level Design document
and a Detailed Design document will provide the necessary level of detail
for those trying to understand the system as a whole, and those trying to
get into the code.<br>
<br>
<h3>High Level Designs</h3>
High level designs provided an overview of the system being documented.
The general concept of the component is described, and the classes involved
are described briefly (no details of the class implementations). &nbsp;In
some cases the high level design vocabulary consists of other components
and not classes. &nbsp;The important thing is to describe the interactions
between the classes and/or components such that the reader gets an understanding
of which pieces talk to which other pieces, what kinds of data are shared
by various components or classes, how the data is modified and by whom, beginning
states and end states of a process, and external constraints or inputs into
the system begin described. <br>
<br>
A fundamental piece of the high-level design is the<b> data model</b>. This
is generally a graphical representation of the classes or components involved
in the system, showing the relationships between them in terms of has-a,
is-a, uses, owns, etc. the specific representation is not as important as
the content of the representation. For example, using UML or Booch notation
is fine, as is an ad-hoc diagram that shows the same types of information.<br>
<br>
Another important piece of the high-level design is a set of <b>use-cases</b>
that describe specific interaction that result from specific events in
the system. For example, we might want to show specifically what happens
when an attribute is changed on an element via the DOM. Use cases differ
from data models in that they show specific instances of objects or components,
actual data values where interesting or important, and often give a glimpse
into the algorithms employed. All of the components or objects in the use
cases must be documented in the data model.<br>
<b><br>
State Transition Diagrams</b> may be important to some systems, and they
should be documented in the high-level design as well. These should be described
in terms of the abstract states that the system may be in, not in terms of
how the state-machine is actually implemented.<br>
<br>
The high-level documents provide an overview of the components and classes
that make up a system. It can be used as a road map to the related detailed
design documents for the components and classes involved in the system. thus,
the classes, components, and algorithms referenced in the high-level design
document should be linked to the detailed design documents that correspond.
This link generally occurs at the first reference to the class or component,
but it can be provided in other contexts as well, for convenience to the reader.
&nbsp;Missing or invalid links are considered errors in the high-level design.
<br>
&nbsp;&nbsp; <br>
<h3>Detailed Designs</h3>
Detailed design documents provide specific information needed to implement
(or understand the implementation of) the components and classes described
in the high-level design. Users of the classes or components should also be
able to understand from the detailed design just how the classes, components
and API's are to be used. Special performance characteristics of methods or
interactions should be documented where pertinent.<br>
<br>
<h4>Public API</h4>
The public API of the component or class being documented is essential to
the detailed design. Each publicly accessible interface, method and data member
must be documented. Ideally this information is contained in the implementation
files for a class, interface or component. If this is the case, the actual
IDL or class header file can be used as the documentation for the public API.
This should be done as a link or embedded document to avoid the perpetual
need to keep the document up to date with the source file. &nbsp;Specific
items that are important to the description of the publicly available aspects
of the component, class, or interface include:<br>
<ul>
<li>entry-point semantics: what does the method do, or what does the data
member mean? Is the universe of expected clients limited or open (e.g.. who
can call it)?<br>
</li>
<li>preconditions: what are the legal states for the instance to be in
before the entry point is called? what are the legal values for the arguments?
what are the required states for the objects or components used in the entry-point?</li>
<li>postconditions: what is guaranteed when the entry-point is returned
from? what return values are legal? what is the status of the output arguments
for various return states?</li>
<li>special performance characteristics: if there are special concerns
about performance of the method, explain them. for example, is the method
O(n^2)? Is there considerable memory required? Is the method recursive?</li>
</ul>
Beyond the public interfaces, the private and protected methods need to
be documented as well. For protected methods and members, the expectations
of the subclasses must be made clear (e.g.. should the subclass call the
base class method? if so, when?) &nbsp;As with the public methods, the semantics,
preconditions, postconditions, and special performance considerations should
be described. Again, this may be by direct inclusion of the source code files
where appropriate.<br>
<br>
<h4>Algorithms</h4>
There is often a need to document specific algorithms used in methods and
functions. &nbsp;Generally, it is not a good idea to include this sort of
information in the source files, so they must be described fully in the detailed
design document. &nbsp;The extent of this information varies wildly from one
design to another. &nbsp;Be sure to include an Algorithms section to the
document when there are interesting or critical algorithms that the classes
or components employ. &nbsp;Spell out the algorithms in as much detail as
possible using pseudo-code or diagrams. Ideally, it should be possible to
implement the algorithm from the information in the design.<br>
<br>
<br>
Algorithms that involve several different components or object instances
require special attention. These algorithms tend to be more complex and more
difficult to completely specify. &nbsp;Start out by referring to the related
use cases in the high level design, and then drill down into the responsibilities
and requirements of the individual instances involved. &nbsp;Here, diagrams
and pseudo-code are indispensable in communicating how the algorithm is carried
out across the system.<br>
<h4></h4>
<h4> Tech Notes</h4>
The end of the detailed design document should contain a list of links to
Tech Notes. These will vary in depth and scope, but generally they provide
information geared toward helping developers work on the system. &nbsp;Tech
Notes might contain information about &nbsp;how code has been modified, how
a new feature was added, how to debug a certain class of problem, how to
use built-in debugging r logging facilities, or how to maintain or extend
unit tests. &nbsp;The Tech Notes should be stored in a publibly accessable
location, as a comment or attachment in a bugzilla bug, for example. &nbsp;The
text that holds the link should be descriptive of what the Tech Note addresses.<br>
<br>
</body>
</html>