Part 1: The Problem
1. Problem summary:
Code documentation. Writing up documentation for code is long and tedious. Javadocs provide a convenient way to imbed documentation in the source code and create documentation from the source code. So, we’d like to implement a baby version of Javadocs for the 164 language… we’ll call it 164doc.
A development scenario that will be less tedious:
Without 164doc: You just finished coding a massive project. Now you have to write up the documentation for your project. You can either write it up yourself or hire someone to write it for you. You majored in computer science, not English, so this could be painful.
With 164doc: While you’re coding your project, take a few moments to add a comment above all the methods you’d like documented. In this comment, you can describe the parameters, return values, authors, etc. You should probably be writing these comments while you’re coding anyways, just to keep track of what you’re doing. Then, once you’ve finished, run your code through the 164doc creator and it will output documentation for you in the form of HTML. No extra writing yay!
2. Why this problem is hard:
Documenting code can be tedious and very detail-oriented. It’s very easy to forget to write about a small detail. Hiring a documentation writer means you have to spend more money.
3. Why this problem is worth solving:
164docs will save programmers a lot of time because they can spend more time coding and less time writing up documentation. It also provides a clean, uniform way of writing comments to make your code more readable.
Part 2: Studying Javadocs
1. Simple code example
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute {@link URL}. The name
* argument is a specifier that is relative to the url argument.
* "<"p">"
* This method always returns immediately, whether or not the
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
* that draw the image will incrementally paint on the screen.
*
* @param url an absolute URL giving the base location of the image
* @param name the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}
The first line contains the begin-comment delimiter, /**. The first sentence in the comments is a short summary of the method, which is placed in the method summary table in the resulting HTML. The inline tag {@link URL} is converted to an HTML hyperlink pointing to the documentation for the URL class. Multiple paragraphs in the description should be separated with a <p> tag. A blank line separates the description from the list of tags. The first line that begins with an “@” ends the description. An @param tag is required by convention for every parameter, even when the description is obvious. The @param tag is followed by the name of the parameter, followed by a description of the parameter. The @return tag is required for every method that returns something other than void, even if it is redundant with the method description. The @return tag is followed by a description of the return value, including special cases whenever possible. The @see tag is followed by a reference. In this case, it is a reference to the java Image class. Many other tags are also supported. The last line contains the end-comment delimiter */. Javadoc takes the doc comment for each class, constructor, field, interface, and method and generates the API for each in HTML.
2. Javadoc Implementation
Javadoc requires and relies on the java compiler. It calls part of javac to compile the code, keeping the declarations and doc comments but discarding the implementation. It builds a parse tree and then generates the HTML from that. Relying on the compiler ensures that the HTML output corresponds exactly with the actual implementation. For example, the compiler creates default versions of constructors that are not present in the source code. If Javadoc did not use the java compiler, it would be difficult to handle these special cases.
for each class, constructor, field, interface, or method:
parse description looking for inlined tags
parse each tag
generate html
Part 3: Features
1. The domain:
The “programs” we intend to write are descriptions of methods coded in the 164 language. For example, we should be able to specify a description (written in HTML), authors and versions for classes, and parameters and return values for functions. Our parser will then parse these fields and generate a HTML document.
2. The programming model:
Our programming model will be declarative programming for parsing (grammars and syntax-directed translation). We’ll write the grammar to parse the 164doc tags, and it will translate it into HTML.
3. Example program:
/**
* Returns the result of computing factorial on the argument.
* "<"p">"
* This function is borrowed from test-advanced.164. It tests
* to make sure the while-loop works.
*
* @param d the integer to compute factorial on
* @return the result of d!
*/
def fact2(d) {
def r = 1
while (1 < d) {
r = r * d
d = d - 1
}
r
}
After parsing, this should produce an HTML document like this:
fact2
fact2(d)
Returns the result of computing factorial on the argument.
This function is borrowed from test-advanced.164. It tests
to make sure the while-loop works.
Parameters:
d – the integer to compute factorial on
Returns:
the result of d!
Part 4: Implementation decisions
Alternative Implementation A: Use syntax-directed translation to parse an input source code file (paying attention to only the 164doc comments) into a BAH document. Then the BAH parser will create the DOM, which can be displayed in the browser.
Alternative Implementation B: The grammar will parse the 164doc comments into an AST, with tuples like (‘description’, [description text]), (‘param’, [param name], [param description]), (‘return’, [return description]), etc. Then our interpreter would interpret this AST and output the BAH document, which could then be rendered with milestone 2.
1. Frontend
A: There is no internal representation; the input source code will be directly translated to BAH using the grammar.
B: The grammar will translate the source program into the AST, as described above. The AST will contain tuples like (‘description’, [description text]), (‘param’, [param name], [param description]), (‘return’, [return description]) for each 164doc comment.
2. The core language
A: No, there is no sugar on top of a simpler-to-implement language.
B: No, there is no sugar on top of a simpler-to-implement language.
3. Internal representation
A: We will represent the document output as a BAH document. The BAH document will then be displayed in the browser (milestone 2 of proj 3). An alternative way would be to represent the document as HTML, then the interpreter would be unnecessary.
B: See the description of the AST above. When we’re interpreting the AST, we can output the document as either BAH or HTML.
4. Interpreter/compiler
A: Because we’re using syntax-directed translation to generate a BAH document, we do not need an interpreter or compiler. The BAH document would be parsed and displayed.
B: The interpreter will interpret each tag of each AST node, then create the BAH/HTML following the AST structure.
5. Debugging
A: To debug the implementation, we would try various test files and make sure it outputs the desired BAH format.
B: To debug this implementation, we would try various test files, make sure the 164doc is translated into the correct AST, and make sure it outputs the desired BAH/HTML format.
No comments:
Post a Comment