View Full Version : Automatic Spin Program Documenter (Online version now available)

Phil Pilgrim (PhiPi)
11-18-2010, 01:14 AM
I love writing programs, but I hate writing documentation. One problem with writing program documentation is that it's so redundant [whine, snivel]. If you've already commented your code, why do it all over again? Another issue I have with documenting code is having to to it with Microsoft Word (which I detest) and then converting it to PDF. This is a problem because such documents are page-oriented, while the subject matter is not. For example, how many times have you had to leaf back and forth in a multi-page source listing, while referring to a description of how it works on yet another page? On the other hand, hypertext formats are just made for documenting code, and that's the route I chose to take.

So, faced with documenting the S2 object I've worked on for several months, loving to program, and hating to document, the solution was obvious: write a program to document the code for me! So that's what I did.

Fortunately, Chip and Jeff had the foresight to include a strategy within Spin itself for self-documenting code. The various commenting layers make it possible to separate document comments from code comments. What Spin provides only sketchily, however, is a presentation layer for the document comments so that the documentation can be viewed in a way that turns them them into a useful reference. That's the gap that I have tried to fill.

The Perl program I've written takes in a Spin file and spits out hyperlinked HTML. This is not something that's new or unique, however. Perl programmers have had such a facility for a long time with Perl's POD (http://perldoc.perl.org/perlpod.html) (plain old documention) markup language and the pod2html (http://perldoc.perl.org/pod2html.html) conversion program. Anyone who's used CPAN or ActiveState's Perl will appreciate the difference that nicely-formatted HTML can make in a document.

POD can be a bit intrusive, though, when sprinkled inline amongst various Perl subroutines and viewed as part of the source code. Consequently, POD sections are usually relegated to the end of the file. I wanted something that would look presentable both within the Spin source and also post-conversion. The idea was that most of the markup would consist of things that people do anyway, with one or two discreet additions for formatting and highlighting the HTML. So here's what I came up with.

Spin's documentation commenting consists of block comments, enclosed in double braces, and one-liners that begin with double apostrophe's:

{{ This is a block comment.
It can go on for many lines.

'' This is a one-line comment.

The program I've written looks for documentation comments sprinkled amongst the source code and manipulates their contents to produce an HTML file, while also including the code itself.

The {{ block comments }} are used to demarcate free-formatted paragraphs. Generally, text within block comments will be formatted to fit the browser page width, regardless of how wide the lines are in the Spin program. And they produce an easy-to-read, proportionally spaced font stripped of the extra spaces that may appear in the Spin source code. Formatting of block comments for conversion purposes is a stricter than it is in Spin, however. The program will only recognize them if the opening {{ are the first non-blank characters in a given line and if the closing }} are the last non-blank characters in a line.

'' One-line comments mark lines that are also documented as separate lines. They're still presented with a proportional font, but leading spaces and extra embedded spaces are preserved. One-line comments are only recognized when the two apostrophes '' appear as the first non-blank characters in a given line.

''' The triple-apostrophe begins a special form of one-line comments. These are used to demarcate a single line wherein the text gets output with a monospaced font. If you have the Parallax font installed (recommended) it will use the Parallax font. These lines are typically used to draw diagrams with Spin's special graphics characters (which get converted to UTF-8 for the HTML output).

{{{ Monospaced block comments }} (note just two ending }s) work like ''' comments, but without the necessity for the prefix at the beginning of each line.

{{{... Monospaced sample code }} (note just two ending }s) provide a way to insert sample code within the object itself without it being compiled with the object. When converted to a document, the contents of this block are displayed in the same way other source code is displayed (i.e. in a drop-down box triggered by clicking the SOURCE CODE... link. The difference here, though, is that clicking anywhere in the displayed source selects all of it, so that it can be copied and pasted into the Propeller Tool.

Finally, one-line comments can be embedded within block comments to format individual lines within a paragraph, say.

The program supports several kinds of headings, shown below. They can be embedded within both block and line comments, with about the same effect. All have the same syntax: <formatting character(s)>[ Heading Text ]<formatting character(s)>. This is in line with the way headings are usually shown in Spin (and even PBASIC) programs anyway, so it's not somehting that will be jarring to see on one's program. In the final document only the Heading Text is shown, not the surrounding brackets and formatting characters. The only cue the conversion program looks for is one formatting character on either side of the brackets. The rest are redundant. For example, -[ Heading Text ]- is sufficient to demarcate a subheading. Here are the heading types:

'':::::::[ Title Heading ]:::::::::::::::::::::::::::::::::::::::::::::::::: :::

'' One title heading should be used at the very top of your program. The text
'' gets displayed centered, with a Table of Contents entry labeled, "Preface".
'' It is used ahead of any copyright and version information that typically
'' appears before the program's CONstant section.

''=======[ Major Section Heading ]=============================================

'' The text between brackets in this kind of heading appears in both the
'' presentation text and in the Table of contents.

''=======[ Major Section Heading... ]==========================================

'' Any section heading ending with an ellipsis (...) is shown in the Table of
'' Contents with the eliipsis, but in the text without. In the ToC, this has a
'' special effect, in that all subsequent, lesser ToC entries are hidden until
'' the entry with the ellipsis is clicked. A subsequent click will again hide
'' the subentries below it, helping to keep the ToC tidy and small.

'' #######[ Major Section Heading ]############################################

'' This is the same as =[ Major Section heading ]=, except that no ToC entry is
'' made. Think of the pound signs as equal signs with cross-hatches that say,
'' "No ToC entry!"

''-------[ Minor Section Heading ]---------------------------------------------

'' The text between brackets in this kind of heading appears in both the
'' presentation text and in the Table of contents.

''-------[ Minor Section Heading... ]------------------------------------------

'' Any section heading ending with an ellipsis (...) is shown in the Table of
'' Contents with the eliipsis, but in the text without. In the ToC, this has a
'' special effect, in that all subsequent, lesser ToC entries are hidden until
'' the entry with the ellipsis is clicked. A subsequent click will again hide
'' the subentries below it, helping to keep the ToC tidy and small. The only
'' entries lesser than a minor heading are method names.

'' +++++++[ Major Section Heading ]++++++++++++++++++++++++++++++++++++++++++++

'' This is the same as -[ Minor Section heading ]-, except that no ToC entry is
'' made. Think of the plus signs as hyphens with cross-hatches that say,
'' "No ToC entry!"

In addition to the above formatting, the only other feature of note is highlighting. Any single word immediately preceded by a backtick (e.g. `boldface) will be shown in boldface.

In most program sections, document text and source code are shown in the order in which they appear. The exceptions are PUB and PRI sections. In these, any document comments appearing within the section (i.e. not at the bottom) are gathered for presentation at the top, after the method heading, but before the source code link. This is in keeping with the practice of the PUB or PRI method line appearing in the source code, then the document comments pertaining to that method, followed by the rest of the method's source code.

I could go on with this long-winded description. But it might be easier just to exhibit an example that encompasses all the features I've mentioned. Attached is the latest source for the S2 Spin object. In it, you can see examples of the markup cues I've mentioned here. Here is a link to the HTML code that my program generated from it:


All the ToC entries and "SOURCE CODE..." tags are hyperlinks that you can play with. I've tested the HTML with Opera (WinXP, OS/X), Firefox (WinXP), and Safari (OS/X). All seem to behave themselves. IE6 was usable, but a disaster from a presentation standpoint. (I don't use IE, so I haven't installed any later versions.) Opera was by far the easiest and most forgiving to develop for; and, IMO, has the best font rendering of all of them.

Anyway, if there are anomalies that you find too distracting, let me know. Meanwhile, I plan to make the spin2html program available as a web service. My web host has to move my site to a different server first to accommodate Perl 5.8, which supports unicode. That should be done by sometime tomorrow.


Addendum: The online documenter is up and running at: http://www.phipi.com/spin2html/.
[b]Addendum (2010.11.26): Added a description (above) regarding the new sample code formatting and updated the S2 object to demonstrate its use.

11-18-2010, 02:03 AM
This is simply BRILLIANT Phil. Congratulations :yeah::yeah::yeah::yeah::yeah:

11-18-2010, 02:10 AM
If we combine Parallax's Propeller tool, Cluso's zero footprint debugger and now Phil's program documenter, would we end up with programs that compile, debug and then document themselves?


11-18-2010, 02:12 AM
Very nice but this unicode stuff makes s2.spin unintelligible in my browsers default text viewer, kate. Hope it still works after I have cleaned it up with iconv:)

11-18-2010, 02:34 AM
@ Phil,

I am using Google's Chrome, instead of Safari, and it appears great. Not using Safari, I don't have anything else to compare it to, but I'd guess it is proper.

Next to 'peek' at your source file to understand how the 'original' document appeared.

11-18-2010, 03:57 AM
This is a really cool idea. And it looks good.

Just curious: Do you write documentation so that you can read it yourself, or so that other can read it?

How often do you read you own documentation?
Any ideas how often other folks read your code?

I tend to document just to organize my thoughts, and the better my documentation, the better my results. Although I seldom read it myself until somebody asks a question.

Phil Pilgrim (PhiPi)
11-18-2010, 04:12 AM

Thanks for the kind words!


Yeah, Kate is probably not the best viewer for Spin source code (UTF-16). BTW, I tried viewing the HTML in Konqueror (3.5.6). Everything looked okay, but the ToC links didn't work. Firefox under the latest Linux Mint (Gnome) worked fine, though.


It depends on who the program is for. If it's just for me, I always comment assembly code, but that's about it. If it's for a wider audience, I add more documentation. In any event, it takes about a month of sitting unread, and then coming back to it, before I can tell whether the documentation is effective. I've had cases, when reading my own documentation months own the road, where I've thought, "How could anyone understand that? Heck, I don't understand it, and I wrote it!"


11-18-2010, 05:43 AM
Phil, excellent work! It makes a very neat and unique web page for easy viewing of documentation and code. I would hope that more programs in the OBEX end up with great documentation like this. Phil, it's always exciting to see your programming projects. Hope you have many more to come.

11-18-2010, 06:00 AM
Excellent work Phil. I have to admit I have thought many times about autodocumenting systems, attempted it once with a Pharma company (whose systems have ridiculous redundancy of documentation, and corresponding opportunity for errors). I couldn't persuade them to join the revolution, unfortunately.

One of my peeves is the lack of quality documentation (ie Manual) that comes with modern software.

For the S2, why not solve this by pressing a secret button combo. Then just load in a texta/marker, and it can write out its (very easy to read large text size) manual :)

11-18-2010, 08:27 AM
Hi Phil,

this is really great! I can't wait to get a possability to create this

Please tell us an estimated date when it will be available.

@Parallax: to encourage submitters of objects to the OBEX
how about some kind of credits that the submitter can achieve
if his object contains a full documentation in this standard?

credits like a percentage for a lower price on parallax products

Of course somebody at parallax would have to read (and understand it).

To keep the time low the bar to jump over has to be hanging high.
and some criteria to check it quickly

Fully documented? EVERY section of the program has a comment?
MIT licence added? small part of the credits

by the way: @PhiPi: how about adding a feature to you software that tells the user which sections, PUBS or PRIs still havent a documenation?

If you read it once and understand it it will get the big part of the credits

If the documenation is not added within in a month by the author anybody
else can claim a comment-right for a week. If a FULLY commented version is submitted within a week THIS submitter will get the credits

These are only spontanious ideas. Maybe some (or all) are not really practical. The main intention of my post is to make parallax think about how can parallax support a high quality documenation of the objetcs?

ALL objects would be commented like S2.SPIN!
The propeller and SPIN would have a reputation of

"very easy to understand because it's so well documented"

best regards


11-18-2010, 08:37 AM
Poor old kate.

The more serious issue was that things like diff don't work on such Spin files. Fortunately kdiff3 does.

Phil Pilgrim (PhiPi)
11-18-2010, 03:00 PM

Kate can work with Unicode Spin files okay. After you've loaded the file, go to Tools->Encoding, and select "Unicode (utf16)".


11-18-2010, 03:11 PM
This is useful work and the program output is nice.

Just FYI: The well known industry standard alternative is doxygen which is mature, multi-platform, multi-language, supports .html/.rtf, and has a configuration wizard.

Doxygen requires adding a C style function declaration (or other recognized language) for each method output to work nicely. Short and simple standardized tags like javadoc @param are used and easy to remember.

Phil's program supports SPIN syntax by default, so it should be easier to use.

11-18-2010, 03:50 PM


Don't know how I missed that setting. Guess I stopped looking down the list of languages after Japanese, Korean or such, not thinking that UTF-16 was a "language".

Phil Pilgrim (PhiPi)
11-19-2010, 04:46 AM
I've gotten the online version working now. Check the top post for the address.


11-19-2010, 06:41 AM
Changing your resize function to the following will make it work under IE and also all other browser I've tested sofar :D

function resize() {
var myWidth = 0, myHeight = 0;
if(typeof(window.innerWidth) == 'number') {
myWidth = window.innerWidth;
myHeight = window.innerHeight;
} else if(document.documentElement && (document.documentElement.clientWidth || document.documentElement.clientHeight)) {
//IE 6+ in 'standards compliant mode'
myWidth = document.documentElement.clientWidth;
myHeight = document.documentElement.clientHeight;
} else if(document.body && (document.body.clientWidth || document.body.clientHeight)) {
//IE 4 compatible
myWidth = document.body.clientWidth;
myHeight = document.body.clientHeight;

document.getElementById("text").style.height = (myHeight - 10) + "px";
document.getElementById("text").style.width = (Math.min(myWidth - 250, 800)) + "px";
document.getElementById("toc").style.height = (myHeight - 10) + "px";

11-19-2010, 06:44 AM
Found a few problems or in msoft speak unintended features :smilewinkgrin:

The tabs do not expand correctly in the first file (interpreter) and the second file (document only) nothing is displayed (perhaps because there is no spin code?)

Of course, neither of these conform to your specifications. I just thought I would run a couple of programs through to see what they looked like.

Phil Pilgrim (PhiPi)
11-19-2010, 07:37 AM

Thanks! That took care of auto-resizing the two panes in IE6. IE6 still has a lot of issues, though, including not handling inline images or understanding the max-height style. But it's a lot better than it was! Thanks again!


I don't have any trouble with the ToC or SOURCE CODE... links expanding with your code. Any lines that require monospaced fonts, though, need to be either in {{{ }} blocks or ' ' ' lines. This includes anything with Spin special graphics characters, such as box outlines. (See the modified heading in the attached.)


11-19-2010, 09:01 AM
Thanks Phil. I just thought it would be worthwhile running the code as is through your program to see the output.

Now I will have to find the time to go through my code - Ah the joys of finding new stuff!

11-19-2010, 11:32 AM
You're welcome,

And yeah inline images can not be handled by IE. I can have a look at the max-height style and see if I can come up with a solution.

Phil Pilgrim (PhiPi)
11-19-2010, 06:27 PM
I guess I should add an alt attribute to the <img> tag, then, so IE has something to display.


11-19-2010, 08:21 PM
Phil: I have no problems that I can see using IE8 & XP2

Phil Pilgrim (PhiPi)
11-19-2010, 09:07 PM

Does the Parallax logo show up in the upper lefthand corner?


It looks like max-height is supported in IE, beginning with IE7. So I think I won't worry about that one.


11-19-2010, 10:09 PM
And data URLs are supported from IE8 onwards, but I think I may have found a solution for IE6,7 that does not require too much aditional javascript (playing around with it at the moment). I only use IE at work, running Linux or OpenBSD on all my computers at home. But it annoys me enough that it does not work properly AND I like the challenge and I keep learning something new every time :)

11-20-2010, 07:56 AM
Hi Phil,

the doc-tool is really great. documenting the parts of a program helps a lot.
For newbees there are still questions left.

I want to a make a suggestion for another feature:
Source code is shown in a non-proportional font.
How about adding another special keyword "DEMO-PRG" where all lines
are shown in this non-proportional font as one piece without interuptions between different methods CON, VAR, DAT-sections?

So that the user can do a mark, copy & paste to extract a compilable and executable demo-prg?

best regards


Phil Pilgrim (PhiPi)
11-20-2010, 04:34 PM

What you're suggesting can be done now:

''==[ Demo Program ]==
PUB start

The demo code won't appear in a drop-down code box, though, but that's something I could add.


Phil Pilgrim (PhiPi)
11-26-2010, 06:50 PM
I took Stefan's suggestion to heart and added a facility for displaying sample code in a way that's more useful. See the first post for details and a revised S2 object that demonstrates its use.


11-28-2010, 06:00 AM
Phil: Sorry to take so long. Yes the Parallax logo is intact.

07-13-2012, 06:36 AM
Since I stumbled about this Thred in another one getting hijacked - I bump this one!

This is another fine piece of work, Phil did and nobody nows about today. This is really nice, integrates EASY with the standart PropTool comments and produces REALLY nice output.

Great work Phil. Good to hear about that newer version you are working on, integrating into the PropTool - waiting with patience, but starting to re-comment my SD-server and SD-client project. V.1.5 its almost ready for the OBEX and I will include your comment-tags. Simple brilliant again. Thank you.



07-13-2012, 07:03 AM
@Phil: The online version rejects valid SPIN files with more than one dot in the name. I see this as an unnecessary restriction.

Phil Pilgrim (PhiPi)
07-13-2012, 07:15 AM

I agree. I guess I didn't have any multi-dotted Spin files to test it with. :) It will have to do for the time being, though. The online program will eventually be replaced by a derivative of the standalone program that I integrated with the Prop Tool. Any corrections I make will be made there first. But none of this will happen without a nod from Parallax. I put a ton of time into this program, but it doesn't make sense to release it if the Gold Standard takes a separate path.


07-14-2012, 09:20 PM

I can not speak for Parallax, but I upgraded FullDuplexSerial from Gold Standard to Autodoc Gold Standard.:smile: (See current Gold Standard Thread. I uploaded them there)

Using your online-converter is very easy and rewarding!

Open your file in PropTool and upload ONCE into the online-converter. Keep the generated file open in the browser.

Now changing the comments, saving the spin in PropTool and just REFRESHING the browser. Click yes to submit again and Tadaa there it is.

Just one thing. Under the Logo you display the File/Objectname capitalized. IMHO it shouldbe left as is to keep the readability ....



Phil Pilgrim (PhiPi)
07-14-2012, 09:36 PM
Nicely done, Mike! (It needs some proof-reading, though, for spelling and capitalization. :) )

Thanks for the suggestion about the title capitalization. I have to agree to some extent. The idea was to give a uniform presentation ahead of the TOC. But, with the possibility of compiling programs under OSes with case-sensitive file systems, perhaps maintaining the file name's case is better. I'll have to think about that one.


07-14-2012, 09:48 PM
Phil, well english is my 3. language. I am native german. So yes proofreading would be nice...



08-20-2012, 04:37 PM
I see from your first post that you made the distinction that this tool is to provide presentation facilities for Spin documentation. My question is why didn't you include tags (or a derivative). They have the advantages of:
- being able to provide links (i.e., if you mention a method name you can provide a link to that method)
- clearly denoting parameters and return values in the source code
- being able to consistently mark deprecated methods

The auto-doc posted in this thread seems good for generating documentation, but makes it difficult to enforce consistency among developers (which could be a debate in and of itself, but I assume that it's a good thing).

In any case, from the Java Autodoc page (http://docs.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html):

The Javadoc tool parses special tags when they are embedded within a Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API from your source code. The tags start with an "at" sign (@) and are case-sensitive -- they must be typed with the uppercase and lowercase letters as shown. A tag must start at the beginning of a line (after any leading spaces and an optional asterisk) or it is treated as normal text. By convention, tags with the same name are grouped together. For example, put all @see tags together.
Tags come in two types:

Block tags - Can be placed only in the tag section that follows the main description. Block tags are of the form: @tag.
Inline tags - Can be placed anywhere in the main description or in the comments for block tags. Inline tags are denoted by curly braces: {@tag}.
For information about tags we might introduce in future releases, see Proposed Tags.
The current tags are:

Tag Introduced in JDK/SDK
@author 1.0
{@docRoot} 1.3
@deprecated 1.0
@exception 1.0
{@inheritDoc} 1.4
{@link} 1.2
{@linkplain} 1.4
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
{@value} 1.4
@version 1.0
For custom tags, see the -tag option.

It seems that the addition of tags would be a helpful addition to this Spin auto-doc utility. What do you think?

Phil Pilgrim (PhiPi)
08-20-2012, 05:05 PM

That's an interesting thought. I already use the backtick (`) to indicate bolface. When a backtick precedes a known keyword, like result, that could be interpreted as a tag of some sort. Beyond that, though, it's not clear to me what use I could make of the tags, given that the doc presentation is already indexed in the left-hand frame, from which it's very easy to zero in on a particular method. Can you give me an example of how you would like to see "tags" used?


08-20-2012, 06:27 PM
Beyond that, though, it's not clear to me what use I could make of the tags, given that the doc presentation is already indexed in the left-hand frame, from which it's very easy to zero in on a particular method. Can you give me an example of how you would like to see "tags" used?

Here is an example from the Java world: JFreeChart.

Generated documentation (http://www.jfree.org/jfreechart/api/javadoc/index.html)
Example source code (http://www.jfree.org/jfreechart/api/javadoc/src-html/org/jfree/chart/axis/Axis.html#line.529)

Here is how it renders in my browser (Chrome in Linux):

I randomly selected the Axis object for this example. Here is an example of two methods from the source code:

529 /**
530 * Sets a flag that controls whether or not the axis line is visible and
531 * sends an {@link AxisChangeEvent} to all registered listeners.
532 *
533 * @param visible the flag.
534 *
535 * @see #isAxisLineVisible()
536 * @see #setAxisLinePaint(Paint)
537 * @see #setAxisLineStroke(Stroke)
538 */
539 public void setAxisLineVisible(boolean visible) {
540 this.axisLineVisible = visible;
541 fireChangeEvent();
542 }
544 /**
545 * Returns the paint used to draw the axis line.
546 *
547 * @return The paint (never <code>null</code>).
548 *
549 * @see #setAxisLinePaint(Paint)
550 */
551 public Paint getAxisLinePaint() {
552 return this.axisLinePaint;
553 }

I feel that one of the most important aspects of the tags is to enforce* consistency among different developers when documenting parameters and return values. But there are also the side benefits of being able to provide links and the like. For example, in the S2 object, at the microphone section (link (http://www.phipi.com/s2/s2_doc.html#lbl34)), there is mention of "start_mic_env" with associated boldface. This could be replaced by the more useful link to that function's documentation.

*enforce is such a harsh word. I think most programmers would be happy to go along with a standard form of documentation, if there was one. Otherwise, we will each come up with a slightly different (and incompatible) scheme.

In these posts I am arguing only for the addition of tags. The Javadoc has lots of other tools, but I haven't had as much exposure to those so I can't comment. Plus, I like the Spin Doc feature of having the method source code available right there to click on.

Phil Pilgrim (PhiPi)
08-20-2012, 06:39 PM
Thanks, Cody. This approach certainly bears further investigation!


08-20-2012, 06:45 PM
These @tags are a very common way of documenting code these days. Eclipse supports @tags and phpdoc parse them to provide contextual information about function calls. PHP doesn't have strict typing, so the code offers no details, however you can specify types using @tags and the resulting documentation blends the two data sources together.

In SPIN, since variables are not typed in declarations, the @tags could provide hints that are then displayed in the resulting docs.

Here is an example: http://www.comcoursedemo.com/html/lms/api/wsapi.html

08-20-2012, 07:10 PM
Parallax has already started using these tags. The examples are not available yet though.

Phil Pilgrim (PhiPi)
08-20-2012, 07:36 PM
Where are they using them? C? Spin?


08-20-2012, 08:00 PM
Where are they using them? C? Spin?


C. Some of us discussed doxygen last year, and it has gained traction.

Doxygen uses a subset of JavaDoc as well as it's own tags.

03-23-2013, 06:25 AM
I tried your documenter today. Really neat :)

It has a few problems with tabbing and linefeeds, else font. While perhpaps you have covered it in your writeup I may have missed this.
I am running WIndows 7 and IE9.