org/nothing/SomeTest.java

1  /*
2  * Copyright 1999-2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16  // (currently lpstart comments at the very start do not work)
17  package org.nothing;
18

What's this?

Based on the Slop parser, Javateach creates a nice HTML page from the source code of a Java class. The idea is to write explanations of the code inline, allowing explanations and code to stay together, and keeping line numbers accurate.

Teaching comments

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. 
29  
30  import org.xml.sax.ContentHandler;
31  import org.xml.sax.SAXException;
32  
33
Here we could explain what class comments are about. 
36  
37  /** Simple example of java code parsing with Slop.
38   *  The aim is to create a minimal "literate programming" system for teaching,
39   *  where java code is decorated with narrative comments. */
40  
41

Here's the class declaration

This class does nothing useful, it does not even compile, it is only used to test the javateach formatting.
Code indentation is preserved, this is set by SlopGenerator parameters in the sitemap. 
49  
50  public class SomeTest implements SlopParser,SlopConstants {
51      private ContentHandler contentHandler;
52  
53      /** chars that can be part of a field name (other than letters) */
54      private final static String DEFAULT_TAGNAME_CHARS = "-_";
55      private String tagnameChars = DEFAULT_TAGNAME_CHARS;
56  
57
lp markers have to start in column 1.
HTML constructs are allowed in lp comments: Links also work, like this. 
67  
68      /** optionally preserve whitespace in input */
69      private boolean preserveSpace = false;
70  
71      /** result of parsing a line */
72      static class ParsedLine {
73          final String name;
74          final String contents;
75  
76          ParsedLine(String elementName, String elementContents) {
77              name = elementName;
78              contents = elementContents;
79          }
80      }
81  
82
SetValidTagname() is used to define a list of valid character for XML element names. 
86  
87      /** set the list of valid chars for tag names (in addition to letters) */
88      public void setValidTagnameChars(String str) {
89          tagnameChars = str;
90      }
91  
92  }