Index: trunk/java/org/apache/cocoon/slop/interfaces/SlopParser.java
===================================================================
--- trunk/java/org/apache/cocoon/slop/interfaces/SlopParser.java	(revision 209915)
+++ trunk/java/org/apache/cocoon/slop/interfaces/SlopParser.java	(working copy)
@@ -13,21 +13,34 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+//@doktor key:SlopParser, filetype:java
 
+/* @doktor-start type:name
+    SlopParser
+    @doktor-end
+*/
+
+//@doktor-start type:package
 package org.apache.cocoon.slop.interfaces;
+//@doktor-end
 
 import org.xml.sax.ContentHandler;
 import org.xml.sax.SAXException;
 import org.apache.cocoon.ProcessingException;
 
+/* @doktor-start type:description
+    This interface dcclares the methods that must be implemented for SLOP parsers.
+    @doktor-end
+*/
+
 /** Interface to SLOP parsers
  *
  * @author <a href="mailto:bdelacretaz@apache.org">Bertrand Delacretaz</a>
- * @version CVS $Id: SlopParser.java,v 1.2 2004/03/05 13:02:23 bdelacretaz Exp $
+ * @version CVS $Id$
  */
- 
+//@doktor-start type;class-declaration 
 public interface SlopParser {
-
+//@doktor-end
    /** must be called before any call to processLine() */
     public void startDocument(ContentHandler destination)
         throws SAXException, ProcessingException;
@@ -40,3 +53,15 @@
     public void processLine(String line)
         throws SAXException, ProcessingException;
 }
+
+//@doktor key:slop, filetype:java, see-also:SlopParser
+
+/* @doktor-start type:name
+    SlopParser
+    @doktor-end
+*/
+
+/* @doktor-start type:description
+    This interface declares the method necessary for an implementation of a SlopParser. The location of this interface is org.apache.cocoon.slop.interfaces.
+    @doktor-end
+*/
\ No newline at end of file
Index: trunk/java/org/apache/cocoon/slop/interfaces/SlopConstants.java
===================================================================
--- trunk/java/org/apache/cocoon/slop/interfaces/SlopConstants.java	(revision 209915)
+++ trunk/java/org/apache/cocoon/slop/interfaces/SlopConstants.java	(working copy)
@@ -13,18 +13,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
+ //@doktor key:SlopConstants, filetype:java
+ 
+ /* @doktor-start type:name
+     SlopConstants
+     @doktor-end
+ */
+ 
+//@doktor-start type:package 
 package org.apache.cocoon.slop.interfaces;
+//@doktor-end
 
+
 /** General constants for the SLOP block
  *
  * @author <a href="mailto:bdelacretaz@apache.org">Bertrand Delacretaz</a>
- * @version CVS $Id: SlopConstants.java,v 1.3 2004/03/05 13:02:23 bdelacretaz Exp $
+ * @version CVS $Id$
  */
-
+//@dokto-start type:class-declaration
 public interface SlopConstants {
     String SLOP_NAMESPACE_URI = "http://apache.org/cocoon/slop/parser/1.0";
-
+//@doktor-end
     // element names
     String SLOP_ROOT_ELEMENT = "parsed-text";
     String SLOP_LINE_ELEMENT = "line";
@@ -33,3 +42,20 @@
     // attribute names
     String SLOP_ATTR_LINENUMBER = "line-number";
 }
+/* @doktor-start type:description
+    This interface just declares some constants for implementing classes in
+    the SLOP block.
+    @doktor-end
+*/
+
+//@doktor key:slop, filetype:java, see-also:SlopConstants
+
+/*@doktor-start type:name
+    SlopConstants
+    @doktor-end
+*/
+
+/*@doktor-start type:description
+    The SlopConstants is just that, an interface with some of the constants for the SLOP block. It is located in org.apache.cocoon.slop.interfaces.
+    @doktor-end
+*/
\ No newline at end of file
Index: trunk/java/org/apache/cocoon/slop/parsing/SimpleSlopParser.java
===================================================================
--- trunk/java/org/apache/cocoon/slop/parsing/SimpleSlopParser.java	(revision 209915)
+++ trunk/java/org/apache/cocoon/slop/parsing/SimpleSlopParser.java	(working copy)
@@ -13,7 +13,22 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+//@doktor key:SimpleSlopParser, filetype:java
+
+/* @doktor-start type:name
+    SimpleSlopParser
+    @doktor-end
+*/
+
+/* @doktor-start type:description
+    This class inplements the SlopParser interface for parsing documents
+    to be made into XML from an unstructured format.
+    @doktor-end
+*/
+ 
+//@doktor-start type:package 
 package org.apache.cocoon.slop.parsing;
+//@doktor-end
 
 import org.xml.sax.ContentHandler;
 import org.xml.sax.SAXException;
@@ -39,7 +54,9 @@
  * @author <a href="mailto:bdelacretaz@apache.org">Bertrand Delacretaz</a>
  * @version $Id$
  */
+//@doktor-start type:class-declaration 
 public class SimpleSlopParser implements SlopParser,SlopConstants {
+//@doktor-end
 
     private ContentHandler contentHandler;
 
@@ -54,6 +71,10 @@
     /** optionally preserve whitespace in input */
     private boolean preserveSpace = false;
 
+    /* @doktor-start type:variable
+        lineCounter - counts the lines during parsing
+        @doktor-end
+    */
     /** count lines */
     private int lineCounter;
 
@@ -86,16 +107,35 @@
         return sb.toString();
     }
 
+    /* @doktor-start type:method, method:setValidTagnameChars
+        Sets the list of valid characters for tag names, that is, 
+        valid characters other than letters.
+    @doktor-end
+    */
     /** set the list of valid chars for tag names (in addition to letters) */
     public void setValidTagnameChars(String str) {
         tagnameChars = (str == null ? DEFAULT_TAGNAME_CHARS : str.trim());
     }
 
+    /* @doktor-start type:method, method:setPreserveWhitespace
+        Sets whether the parser preserves the whitespace in input.
+    @doktor-end
+    */
     /** optionally preserve whitespace in input */
     public void setPreserveWhitespace(boolean b) {
         preserveSpace = b;
     }
 
+    /* @doktor-start type:warning
+        The startDocument method must be called before processLine().
+        startDocument can throw a SAXException or a ProcessingException
+    @doktor-end
+    */
+    /* @doktor-start type:method, method:startDocument
+        For starting a document using SAX parsing. This method must be called before 
+        processLine().
+    @doktor-end
+    */
     /** must be called before any call to processLine() */
     public void startDocument(ContentHandler destination)
     throws SAXException, ProcessingException {
@@ -105,6 +145,11 @@
         contentHandler.startElement(SLOP_NAMESPACE_URI, SLOP_ROOT_ELEMENT, SLOP_ROOT_ELEMENT, XMLUtils.EMPTY_ATTRIBUTES);
     }
 
+    /* @doktor-start type:method, method:endDocument
+        This method ends a document using SAX. This method is called after all calls
+        to processLine() are complete.
+    @doktor-end
+*    /
     /** must be called once all calls to processLine() are done */
     public void endDocument()
     throws SAXException, ProcessingException {
@@ -114,12 +159,20 @@
         contentHandler = null;
     }
 
+    /* @doktor-start type:method, method:setAttribute
+        This method adds simple name-value pairs to be added to the current element.
+    @doktor-end
+    */
     /** add simple name-value attribute to attr */
     private void setAttribute(AttributesImpl attr,String name,String value) {
         final String ATTR_TYPE = "NMTOKEN";
         attr.addAttribute("",name,name,ATTR_TYPE,value);
     }
 
+    /* @doktor-start type:method, method:ProcessLine
+        This method does the actual parsing, line by line.
+    @doktor-end
+    */
     /** call this to process input lines, does the actual parsing */
     public void processLine(String line)
     throws SAXException, ProcessingException {
@@ -139,6 +192,10 @@
         contentHandler.endElement(SLOP_NAMESPACE_URI, p.name, p.name);
     }
 
+    /* @doktor-start type:method, method:ParsedLine
+        This method parses a line and grabs the element name and contents.
+    @doktor-end
+    */
     /** parse a line, extract element name and contents */
     protected ParsedLine parseLine(String line) {
         ParsedLine result = null;
@@ -188,3 +245,15 @@
         return result;
     }
 }
+
+//@doktor key:slop, filetype:java, see-also:SimpleSlopParser
+
+/* @doktor-start type:name
+    SimpleSlopParser
+    @doktor-end
+*/
+
+/*@doktor-start type:description
+    The implementation of the SlopParser interface is SimpleSlopParser.java. It is located in package org.apache.cocoon.slop.parsing.
+    @doktor-end
+*/
Index: trunk/java/org/apache/cocoon/slop/generation/SlopGenerator.java
===================================================================
--- trunk/java/org/apache/cocoon/slop/generation/SlopGenerator.java	(revision 209915)
+++ trunk/java/org/apache/cocoon/slop/generation/SlopGenerator.java	(working copy)
@@ -14,7 +14,21 @@
  * limitations under the License.
  */
 
+ //@doktor key:SlopGenerator, filetype:java
+ 
+/*@doktor-start type:name
+    SlopGenerator
+   @doktor-end
+*/
+
+/* @doktor-start type:description
+    This class is implements a Cocoon generator for the SLOP block.
+    @doktor-end
+*/
+ 
+//@doktor-start type:package 
 package org.apache.cocoon.slop.generation;
+//@dokto-end
 
 import java.io.IOException;
 import java.io.InputStreamReader;
@@ -35,27 +49,34 @@
 import org.xml.sax.SAXException;
 import org.xml.sax.helpers.LocatorImpl;
 
+
 /**
  * SlopGenerator: Simple Line-Oriented Parsing of text files.
  * General code structure lifted from the Chaperon TextGenerator - thanks Stephan!
  *
  * @author <a href="mailto:bdelacretaz@apache.org">Bertrand Delacretaz</a>
- * @version CVS $Id: SlopGenerator.java,v 1.5 2004/03/05 13:02:23 bdelacretaz Exp $
+ * @version CVS $Id$
  */
-
+//@doktor-start type;class-declaration 
 public class SlopGenerator extends ServiceableGenerator
         implements CacheableProcessingComponent {
-
+//@doktor-end
     private Source inputSource = null;
     private String encoding = null;
     private SlopParser parser = null;
     private boolean preserveSpace = false;
     private String validTagnameChars = null;
 
+    
+    /* @doktor-start type:method, method:recycle
+        Recycles this component,
+        sets all instance variables to null.
+        @doktor-end
+    */
     /**
      * Recycle this component.
      * All instance variables are set to <code>null</code>.
-     */
+     */ 
     public void recycle() {
         if (inputSource != null) {
             super.resolver.release(inputSource);
@@ -69,6 +90,11 @@
         super.recycle();
     }
 
+    
+    /* @doktor-start type:method, method:setup
+        Sets the SourceResolver, objectModel Map, the source and sitemap
+        @doktor-end
+    */
     /**
      * Set the SourceResolver, objectModel Map, the source and sitemap
      * Parameters used to process the request.
@@ -100,6 +126,10 @@
         }
     }
 
+    /* @doktor-start type:method, method:getKey
+        Generates the unique key
+        @doktor-end
+    */
     /**
      * Generate the unique key.
      * This key must be unique inside the space of this component.
@@ -110,6 +140,10 @@
         return inputSource.getURI();
     }
 
+    /* @doktor-start type:method, method:getValidity
+        Generate the Validity Object
+        @doktor-end
+    */
     /**
      * Generate the validity object.
      *
@@ -120,6 +154,10 @@
         return this.inputSource.getValidity();
     }
 
+    /* @doktor-start type:method, method:generate
+        Generate the XML data
+        @doktor-end
+    */
     /**
      * Generate XML data.
      *
@@ -187,4 +225,28 @@
         // done parsing
         parser.endDocument();
     }
-}
\ No newline at end of file
+}
+
+ //@doktor key:slop, filetype:java, see-also: SlopGenerator
+ 
+/*@doktor-start type:name
+    SlopGenerator
+   @doktor-end
+*/
+
+/* @doktor-start type:description, name:SlopGenerator
+    This class is an implementation of a SAX-based Cocoon generator. It can be specified as the generator in a Cocoon pipeline. It is located in org.apache.cocoon.slop.generation.
+    @doktor-end
+*/
+
+/*@doktor-start type:sitemap-params, name:SlopGenerator
+    The SlopGenerator accepts three sitemap parameters.
+    names => 'encoding', 'preserve-space', and 'valid-tagname-chars'
+    Encoding might be set to a value of iso-8859-1 and represents the
+    text encoding.
+    Preserve-space is a true or false value and specifies whether or not the
+    generator preserves the whitespace as is or collapses it.
+    Valid-tagname-chars specifies what characters are to be considered valid
+    in tagnames.
+    @doktor-end
+*/    
\ No newline at end of file
Index: trunk/samples/javateach/java-source/org/nothing/SomeTest.java
===================================================================
--- trunk/samples/javateach/java-source/org/nothing/SomeTest.java	(revision 209915)
+++ trunk/samples/javateach/java-source/org/nothing/SomeTest.java	(working copy)
@@ -13,9 +13,21 @@
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
+//@doktor key:SomeTest filetype:jave
+
+/*@doktor-start type;name
+    SomeTest
+    @doktor-end
+*/
+/*@doktor-start type:description
+    This class is an example of the Java Teach functionality.
+    @doktor-end
+*/
+
 // (currently lpstart comments at the very start do not work)
 package org.nothing;
 
+//@doktor-start type;codeblock, codeblock:Teaching Comments 
 //lpstart:
 //  <h1>What's this?</h1>
 //  Based on the Slop parser, Javateach creates a nice HTML page from the source code of a Java class.
@@ -26,18 +38,23 @@
 //  Comments like this one, surrounded by lpstart/lpend will be extracted from the source
 //  code to create an HTML presentation which mixes teaching comments and code.
 //lpend:
+//@doktor-end
 
 import org.xml.sax.ContentHandler;
 import org.xml.sax.SAXException;
 
+//@doktor-start type:example
 //lpstart:
 //  Here we could explain what class comments are about.
 //lpend:
+//@doktor-end
 
+
 /** Simple example of java code parsing with Slop.
  *  The aim is to create a minimal "literate programming" system for teaching,
  *  where java code is decorated with narrative comments. */
 
+
 //lpstart:
 //  <h2>Here's the class declaration</h2>
 //  This class does nothing useful, it does not even compile, it is only used to
@@ -54,6 +71,7 @@
     private final static String DEFAULT_TAGNAME_CHARS = "-_";
     private String tagnameChars = DEFAULT_TAGNAME_CHARS;
 
+//@doktor-start type;example    
 //lpstart:
 // lp markers have to start in column 1.
 // <br/>
@@ -64,6 +82,7 @@
 // </ul>
 // Links also work, like <a href="http://www.perdu.com" target="_new">this</a>.
 //lpend:
+//@doktor-end
 
     /** optionally preserve whitespace in input */
     private boolean preserveSpace = false;
Index: trunk/samples/javateach/jt-to-html.xsl
===================================================================
--- trunk/samples/javateach/jt-to-html.xsl	(revision 209915)
+++ trunk/samples/javateach/jt-to-html.xsl	(working copy)
@@ -17,14 +17,23 @@
 
 <!--
     Convert slop output to HTML for the javateach sample
-    $Id: jt-to-html.xsl,v 1.2 2004/03/06 02:25:42 antonio Exp $
+    $Id$
 -->
 <xsl:stylesheet
     version="1.0"
     xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     xmlns:slop="http://apache.org/cocoon/slop/parser/1.0"
 >
+<!--@doktor key:jt-to-html, filetype:XSLT -->
 
+<!--@doktor-start type:name
+    jt-to-html
+@doktor-end -->
+
+<!--@doktor-start type:description
+     This file transforms the Java-Teach files into an html format for using them in this hybrid state to teach Java. Crazy!
+@doktor-end -->
+
     <xsl:param name="pageTitle" select="'Javateach sample - using the Cocoon SLOP parser'"/>
 
     <!-- keys based on last preceding lpstart or lpend, used to split between code and teaching comments -->
@@ -71,10 +80,12 @@
         </div>
     </xsl:template>
 
+    <!--@doktor-start type:codeblock, name:teachingComments-->
     <xsl:template match="slop:*" mode="teachingComments">
         <xsl:value-of select="concat(substring-after(.,'//'),'&#xD;')" disable-output-escaping="yes"/>
     </xsl:template>
-
+    <!--@doktor-end -->
+    <!--@doktor-start type:codeblock, name:Code lines -->
     <xsl:template match="slop:*" mode="code">
         <span class="lineNumber">
             <xsl:value-of select="concat(@line-number,'  ')"/>
@@ -83,5 +94,16 @@
             <xsl:value-of select="concat(.,'&#xD;')"/>
         </span>
     </xsl:template>
+    <!--@doktor-end -->
 
 </xsl:stylesheet>
+
+<!--@doktor-start type:detail,  name:teachingComments 
+    This block of XSLT processes a "teachingComment" to mix in
+    with the Java code(in hTML)  for educational purposes.
+@doktor-end-->
+
+<!--@doktor-start type:detail, name:teachingComments 
+    This piece of XSLT is for transforming lines of code into
+    displayable HTML for instructional purposes.
+@doktor-end-->
\ No newline at end of file
Index: trunk/samples/sitemap.xmap
===================================================================
--- trunk/samples/sitemap.xmap	(revision 209915)
+++ trunk/samples/sitemap.xmap	(working copy)
@@ -14,11 +14,18 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
-
+<!--@doktor key:slop samples sitemap, filetype:sitemap -->
 <!-- sitemap for slop block samples -->
+<!--@doktor-start type:name
+sitemap.xmap
+@doktor-end -->
 
 <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
+<!--@doktor-start type:description
+    This sitemap really just maps files up to requests for them. The
+    only one that really gets processed is welcome.xml. See the included element.
 
+@doktor-end -->
   <map:pipelines>
 
     <map:pipeline type="caching">
@@ -27,6 +34,7 @@
         <map:redirect-to uri="welcome"/>
       </map:match>
 
+      <!--@doktor-element type:codeblock, codeblock:Match "welcome" and transform welcome.xml for serializing. -->
       <map:match pattern="welcome">
         <map:generate src="welcome.xml"/>
         <map:transform src="context://samples/common/style/xsl/html/simple-samples2html.xsl">
@@ -47,14 +55,18 @@
             <map:read src="javateach/{2}.css" mime-type="text/css"/>
         </map:match>
 
+        <!-- @doktor-start key:slop, type:sitemap-example, name:SlopGenerator -->
         <map:match pattern="javateach/**/*.xml">
             <map:generate type="slop" src="javateach/java-source/{1}/{2}.java">
                 <map:parameter name="encoding" value="iso-8859-1"/>
                 <map:parameter name="preserve-space" value="true"/>
                 <map:parameter name="valid-tagname-chars" value="/-_"/>
             </map:generate>
+        <!-- ... @doktor-end -->    
             <map:serialize type="xml"/>
         </map:match>
+        
+<!--@doktor key:slop samples sitemap, filetype:sitemap -->
 
         <map:match pattern="javateach/**/*.html">
             <map:generate src="cocoon:/javateach/{1}/{2}.xml"/>
@@ -64,6 +76,10 @@
             <map:serialize type="html"/>
         </map:match>
 
+        <!--@doktor-start type:warning
+            This uses the same pipeline for RFC822 and TC now, they may
+            be separated in the future.
+        @doktor-end-->
         <!--
             use the same pipeline for rfc822 and tc for now, they can later
             be separated to use different configurations of the SlopParser
Index: trunk/samples/welcome.xml
===================================================================
--- trunk/samples/welcome.xml	(revision 209915)
+++ trunk/samples/welcome.xml	(working copy)
@@ -14,6 +14,14 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
+<!--@doktor key:Welcome, filetype:xml -->
+<!--@doktor-start type:name
+Welcome.xml
+@doktor-end -->
+<!--@doktor-start type:description
+    This is just the SLOP block's welcome page for checking out the SLOP
+    block's samples.
+@doktor-end  -->
 <samples xmlns:xlink="http://www.w3.org/1999/xlink" name="Slop Block Samples">
 
     <group name="Back">
Index: trunk/conf/slop-generator.xmap
===================================================================
--- trunk/conf/slop-generator.xmap	(revision 209915)
+++ trunk/conf/slop-generator.xmap	(working copy)
@@ -14,10 +14,21 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
+<!-- @doktor-start key:SLOP Generator, type:description -->
+<!--
+    The SLOP block configures a special generator for use processing the files
+    into XML content and making those make some sense.
+    
+    This file configures that generator, org.apache.cocoon.slop.generation.SlopGenerator,
+    for use.
+-->
+<!-- @doktor-end-->
 <xmap xpath="/sitemap/components/generators" unless="generator[@name='slop']">
+    <!--@doktor-start key:slop, type:example, name:slop generator  -->
     <map:generator
         name="slop"
         logger="sitemap.generator.slop"
         src="org.apache.cocoon.slop.generation.SlopGenerator"
     />
+    <!--@doktor-end -->
 </xmap>