I can not speak for Parallax, but I upgraded FullDuplexSerial from Gold Standard to Autodoc Gold Standard. (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 ....
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.
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).
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?
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?
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.
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 }
543
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), 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.
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.
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.
Is there a trick to saving the generated html? I'm using Chrome and saving the page as... All the anchor tags change to an absolute address. ie. http:// www. phipi.com/cgi-bin. The rendered HTML looks fine no absolute links and I can copy and paste the HTML no problem.
I'm getting ready to build a command line utility to save the HTML but before I do I want to make sure I'm not missing something simple.
tried it with chrome and Opera (TB currentyl not running on my notebook.
links in the right half are local
the links of the table of content still direct to your website
Comments
I can not speak for Parallax, but I upgraded FullDuplexSerial from Gold Standard to Autodoc Gold Standard.
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 ....
Enjoy!
Mike
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.
-Phil
Enjoy!
Mike
- 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:
It seems that the addition of tags would be a helpful addition to this Spin auto-doc utility. What do you think?
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?
-Phil
Here is an example from the Java world: JFreeChart.
Generated documentation
Example source code
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 } 543 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), 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
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
-Phil
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.
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.
LMM_SerialDebugger_020.spin
I'm getting ready to build a command line utility to save the HTML but before I do I want to make sure I'm not missing something simple.
-Phil
tried it with chrome and Opera (TB currentyl not running on my notebook.
links in the right half are local
the links of the table of content still direct to your website
best regards
Stefan