[Gump Wiki] Updated: GumpRunDocumentation

[ge...@gump.apache.org]

   Date: 2004-03-29T09:48:27
   Editor: AdamJack <aj...@apache.org>
   Wiki: Gump Wiki
   Page: GumpRunDocumentation
   URL: http://wiki.apache.org/gump/GumpRunDocumentation

   no comment

Change Log:

------------------------------------------------------------------------------
@@ -1,13 +1,68 @@
 == GumpRunDocumentation ==
 
-Gump Run Documentation is documentation about a Gump run, not about [http://gump.apache.org|Gump]. 
+Gump Run Documentation is documentation about a Gump run, not about [http://gump.apache.org Gump]. 
 
 == How things work today ==
 
-Gump currently supports two forms of documentation (plain text and xdocs, for[http://xml.apache.org/forrest|Apache Forrest]). 
+Gump currently supports two forms of documentation (plain text and xdocs, for[http://xml.apache.org/forrest Apache Forrest]). The reason for this is that although Forrest generates impresive sites, it is time consuming and not ubiquitously available. Folks have the choice of simple/cheap or pretty.
+
+=== Overview ===
+
+Currently 'documentation' is a task performed at the end of a run, so it has the all context (states, outcomes) available. This is important for 'statistics' and 'xref' pages, which display pages that compare/sort all modules/projects so needs all to be complete, and have complete information. 
+
+Note: That said, this could be split into two parts -- with pages for single modules/projects being creates as available (much sooner) and only the cross entity pages created last.
+
+=== Implementation ===
+
+Documented is achieved using a few classes:
+
+* Resolver -- that resolves a model object (e.g. a project) to a URL or file.
+* Documenter -- that works with it's resolver to generate those files.
 
 === Resolver ===
 
+This component is important in part because other aspects (e.g. RSS|Atom feeds, Notification e-mails) need to be able to refer to some aspect (a failed work item, a project page) without knowing which documenter was user. Also, this can be quite complicated (especialyl for Forrest with content and content/xdocs) and we need to centralize the logic to avoid duplication/error.
+
 === Documenter ===
+
+This component is the meat of the documentation process. A GumpRun (with complete information) is traversed, and information is generated for all entities in the GumpSet (a list or dependency stack).
+
+Two documentation classes exist as sub-classes of gump.documentation.Documenter:
+
+* gump.documentation.ForrestDocumenter
+* gump.documentation.TextDocumenter
+
+=== ForrestDocumenter ===
+
+This module is huge, but that is only because it has a lot of repetative (template-ish) code. 
+
+The overall algorythm used for documentation is:
+
+ Document the workspace (see block below)
+ For each module in workspace:
+  If module not in gump set: continue
+  Document the module (see block below)
+  For each project in module:
+   If project not in gump set: continue
+   Document the project(see block below)
+
+Basically each block looks like this:
+
+ * Select a file for an entity (the resolver determines the name/where)
+ * Generate xdoc sections (e.g. details, or dependencies or)
+ * Generate details by adding paragraphs or lists/list items as needed.
+ * Iterate through information (e.g, annotations) adding tables/rows/data.
+ * Serialize the xdocs (DOM-like tree) to that file.
+ * Throw away all memory used by the tree.
+
+Note: Some re-used blocks are:
+
+ * Generate a section (with table with rows/data) for all Annotations
+ * Generate a section (with table with rows/data) for all Files held by FileHolder
+ * Generate a section (with list/items) for Statistics
+
+=== xdocs ===
+
+
 
 == How we could take them forward ==

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@gump.apache.org
For additional commands, e-mail: general-help@gump.apache.org