Casdoc Transformer

Use the field below to transform annotated Java code examples into Casdoc HTML documents. To create a new annotated code example from scratch, start by creating a Java file using your favorite IDE, then use the annotation language described below to add the additional explanations directly in your code as block comments surrounded by /*? and */.

This version of the transformer is consistent with what was presented at ICPC 2022. We since made some improvements to Casdoc, which include visual changes and a new "Walkthrough" feature. You can find examples of the new documents here. There is no public service for the new version. Please contact us if you are interested in using Casdoc for educational, academic, or commercial purposes.

This service is free, but requires you to create an account.
You can login/register here.

Logged in as
Logout or change account (this will bring you back to the login page.)

Annotated Java File Require Login

For example, try the following files as starters:

• FunctionalProgrammingDemo.java (see the result)
• JavaReflectionDemo.java (see the result)
• SqlDatabaseConnectionDemo.java (see the result)

Annotation Language

Users can annotate code examples with custom content using Casdoc's markup language. Annotations should be added within popover comments. Popover comments begin with /*? and end with */, ending directly one line above the intended code anchor. Within popover comments, users can specify what type of popover they would like to add, to which anchor, and with what content.

Types of Popovers

Keyword Popovers

Keyword Popovers are popovers whose anchor exists within one line of code. These are useful for when users want to highlight a single keyword or statement. For example, describing the use of a variable. Anchors to keyword popovers can include non-alphanumeric characters and white spaces, except for the character ":".

Annotation Syntax

Keyword:Anchor
Content

adds popover with specified Content to Anchor.

Example:

Keyword:aCards
aCards is a field that represents cards in a deck.

Block Popovers

Block Popovers are popovers whose anchor consists of one entire line or more. These are useful for when users want to highlight larger chunks of code, for example a for-loop.

Annotation Syntax

Block:Lines
Title
Content

adds popover with Title and Content to the number of Lines below this comment. The line count should also include lines consisting of only comments.

Example:

Block:4
For-Loop
This for-loop iterates through aCards.

Internal Popovers

Internal Popovers are popovers whose anchor exists in another popover, or not in the Java code. In other words, a popover within a popover. These are useful for when users want to highlight a keyword within a block/pedagogical or even another internal popover.

Annotation Syntax

Internal:Anchor
ParentAnchor
Content

adds an internal popover to Anchor within the contents of popover attached to ParentAnchor. This must be placed after the parent popover in the same popover comment.

Example:

Internal:Deck
aCards
A deck has 52 cards.

Anchor

An anchor denotes the piece of code that a popover is attached to. For Block Popovers, this is one line or more. For Keyword and Internal popovers, anchors are strings within one line of code. Keyword and Internal anchors must adhere to the following rules:

• If users want to attach a Keyword or Internal popover to the second occurance of an anchor, then the anchor should be changed to Anchor:n, with n representing the n^th occurance. For example,

Keyword:Rank:2
CONTENT

adds CONTENT to the second occurance of keyword Rank.

• They can contain any special character, with the exception of ":".
• If the anchor is more than one character, it cannot consist of solely non-alphanumeric characters. For example, <?> is an unacceptable anchor.
• The anchor cannot be the entire line of code.

External Resources

Within each popover, an external resource can be added to give users more information. To specify, syntax URL: link should be added as the last line of a popover annotation. For instance,

Keyword:Rank
This is a rank.
URL: https://www.w3schools.com/html/html_links.asp

In the above example, Keyword Popover with anchor Rank has external reference https://www.w3schools.com/html/html_links.asp.

Example of Popover Comment with All Popover Types

/*?
* Keyword:aCards
* aCards is a field that represents cards in a deck.
* 
* Internal:deck
* aCards
* A deck has 52 cards.
* 
* Block:1
* Field
* This is a field.
*/

Adding Popovers to Comment Content

Popover comments should be added directly above the comment users want to annotate. Keyword and Internal popover annotation is as describe above. If users want to add Block popovers, however, lines should be specified by ranges.

Example:

Block:4-5
@pre
The @pre is a special tag used to document precondition
for executing the constructor as part of a technique
called Design by Contract.

adds popover with Title and Content to two lines, starting at line 4 to line 5 beneath this comment.

Notes:

• Popover comments should only contain popover annotations.
• Anchors can include special characters, except for ':'.