Documentation ideas

The ideal for documentation creation

I find that the type of documentation I want to write isn't well supported by the tools I've found. In particular, I typically like to write documentation at three levels. First, there should be a high-level overview, defining the overall purpose and ideas behind a module of code. This should be followed by detailed description of every element in a source file. Finally, I'd like to provide a line-by-line commentary of each function, commenting on the particulars of its implementation. This documentation should, as necessary, include equations, diagrams, images, flow charts, videos, etc. Because code changes frequently, all code snippets or references to names within the code should be easily refreshed by applying a tool.

I see variants of this approach in use for several types of documentation. I typically write code for other programmers, rather than end users. Therefore, my "users" will be fellow programmers desiring to make use of a module I've created. For these users, a high-level explanation of a given header file followed by a description of each element of the header, provides all the information they need to make use of the module. For fellow developers, I'd like to present the same high-level overview, this time focusing of the algorithms used to implement elements declared in the header. This information naturally belongs with the source file the header accompanies. Next, a per-element detailed description of the source file might also be accompanies by a line-by-line analysis of some of the subtle portions of the code. (On a side note, I'd like to use this to develop and updated version of the PIC24 book I co-authored).

My dream implementation would be seamless: a fully-featured word-processing program in which I can type code or in-line documentation, including snippets of code in explanatory sections as necessary. All documentation would be transparently encoded in the raw source file. No such tool exists, to the best of my knowledge.

Existing tools

There's nothing new under the sun, including this idea. Its best-known formulation, Literate Programming by none other than Donald Knuth, "regards a program as a communication to human beings rather than as a set of instructions to a computer. Your program is also viewed as a hypertext document, rather like the World Wide Web." (from an associated site). While WEB (Knuth's tool) operates on Pascal to produce TeX documents, a more modern version (CWEB) applies the same process to C. The literate programming site provides additional information on these ideas; several other notable implementations (FunnelWeb, Noweb). The practical result (here's a sample of some code) is that a program is written in CWEB syntax (mixed C and TeX), then transformed to either C or TeX, making it painful (IMHO) to either write documentation or develop code!

An opposite approach is to embed documentation into the source code, simplifying the build process but still requiring a translation step to produce documentation. Doxygen (along with variants such as JavaDoc), my favorite documentation tool which I've used for several years, excels at extracting documentation from code and producing a polished, nicely cross-referenced result -- the middle level (describing each element) of my documentation hierarchy. However, it contains several major flaws, IMHO:

1. There's no way to directly edit the resulting documentation. I often find a typo or other small correction when browsing through the documentation, which then requires that I dig up the corresponding source, edit it, recompile the docs, and check. This discourages quick fixes.
2. Writing high-level documentation is painful; editing text then compiling reminds me of all the evils of LaTeX without any of the helpfulness of word wrapping, TexWorks docs-to-source synchronization, or quick compilation.
3. There's no way to write line-by-line commentary for a detailed look at an algorithm.
4. Including non-textual media is painful.
5. Trying to fix syntax errors in the source code documentation tags is painful.

Recently, Python adopted use of Sphinx and reStructured text to produce their documentation, which is very impressive. It seems a step back from Doxygen, since there's no automatic linking to source code, while suffering from all its liabilities. The same is true of other alternatives I've found, such as antiweb.

Proposed solution

So, I'd like to create yet another documentation tool, in the (most likely vain) hope it will have some impact. My ideas:

1. I'd like to be able to open some source code in a modern, fully-featured word processor, add documentation (images, diagrams, etc.), then save the result (including any changes I made to the code) back to both the source file and its accompanying documentation file.
2. The program should support documenting only selected portions of the code; for example, I'd typically omit a copyright notice appearing at the top of every file. It should allow adding comments to arbitrary snippets of code, rather than just as the API level (Doxygen's strength), and placing multiple copies of these snippets in arbitrary order within the code.
3. All snippets should be auto-refreshable by reflecting any changes made to the source code. They should follow any source code changes such as moving code around, changing names, etc.

After pondering how I can implement this in as simple a fashion as possible, I've converged on the following design:

1. Label the start of a snippet with a tag marked by rarely-used delimiters, such as &|tag|&.
2. Auto-generate these tags when the documentation file is edited then saved.
3. Auto-refresh all snippets when the documentation file is opened by matching source code tagged snippets with their tagged snippets in the documentation file.

I've chosen Microsoft Word as a word processor and begun writing code in VBA (Visual Basic for Applications), Word's macro language. There's little good documentation on the language I've found; the built-in help is poor, MSDN lacks in many areas, and even searching the web produces mediocre results. I may purchase a book to help. I haven't found a good unit-testing framework for Word; a framework for Excel seems fairly tied to that platform.

So far, I've written code that divides a source file into named snippets; not bad progress, but there's much more to do. I should probably next:

1. Write unit tests, which I should have done first.
2. Create a good, high-level document to describe all this in more detail.

Documentation ideas

The ideal for documentation creation

I find that the type of documentation I want to write isn't well supported by the tools I've found. In particular, I typically like to write documentation at three levels. First, there should be a high-level overview, defining the overall purpose and ideas behind a module of code. This should be followed by detailed description of every element in a source file. Finally, I'd like to provide a line-by-line commentary of each function, commenting on the particulars of its implementation. This documentation should, as necessary, include equations, diagrams, images, flow charts, videos, etc. Because code changes frequently, all code snippets or references to names within the code should be easily refreshed by applying a tool.

I see variants of this approach in use for several types of documentation. I typically write code for other programmers, rather than end users. Therefore, my "users" will be fellow programmers desiring to make use of a module I've created. For these users, a high-level explanation of a given header file followed by a description of each element of the header, provides all the information they need to make use of the module. For fellow developers, I'd like to present the same high-level overview, this time focusing of the algorithms used to implement elements declared in the header. This information naturally belongs with the source file the header accompanies. Next, a per-element detailed description of the source file might also be accompanies by a line-by-line analysis of some of the subtle portions of the code. (On a side note, I'd like to use this to develop and updated version of the PIC24 book I co-authored).

My dream implementation would be seamless: a fully-featured word-processing program in which I can type code or in-line documentation, including snippets of code in explanatory sections as necessary. All documentation would be transparently encoded in the raw source file. No such tool exists, to the best of my knowledge.

Existing tools

There's nothing new under the sun, including this idea. Its best-known formulation, Literate Programming by none other than Donald Knuth, "regards a program as a communication to human beings rather than as a set of instructions to a computer. Your program is also viewed as a hypertext document, rather like the World Wide Web." (from an associated site). While WEB (Knuth's tool) operates on Pascal to produce TeX documents, a more modern version (CWEB) applies the same process to C. The literate programming site provides additional information on these ideas; several other notable implementations (FunnelWeb, Noweb). The practical result (here's a sample of some code) is that a program is written in CWEB syntax (mixed C and TeX), then transformed to either C or TeX, making it painful (IMHO) to either write documentation or develop code!

An opposite approach is to embed documentation into the source code, simplifying the build process but still requiring a translation step to produce documentation. Doxygen (along with variants such as JavaDoc), my favorite documentation tool which I've used for several years, excels at extracting documentation from code and producing a polished, nicely cross-referenced result -- the middle level (describing each element) of my documentation hierarchy. However, it contains several major flaws, IMHO:

1. There's no way to directly edit the resulting documentation. I often find a typo or other small correction when browsing through the documentation, which then requires that I dig up the corresponding source, edit it, recompile the docs, and check. This discourages quick fixes.
2. Writing high-level documentation is painful; editing text then compiling reminds me of all the evils of LaTeX without any of the helpfulness of word wrapping, TexWorks docs-to-source synchronization, or quick compilation.
3. There's no way to write line-by-line commentary for a detailed look at an algorithm.
4. Including non-textual media is painful.
5. Trying to fix syntax errors in the source code documentation tags is painful.

Recently, Python adopted use of Sphinx and reStructured text to produce their documentation, which is very impressive. It seems a step back from Doxygen, since there's no automatic linking to source code, while suffering from all its liabilities. The same is true of other alternatives I've found, such as antiweb.

Proposed solution

So, I'd like to create yet another documentation tool, in the (most likely vain) hope it will have some impact. My ideas:

1. I'd like to be able to open some source code in a modern, fully-featured word processor, add documentation (images, diagrams, etc.), then save the result (including any changes I made to the code) back to both the source file and its accompanying documentation file.
2. The program should support documenting only selected portions of the code; for example, I'd typically omit a copyright notice appearing at the top of every file. It should allow adding comments to arbitrary snippets of code, rather than just as the API level (Doxygen's strength), and placing multiple copies of these snippets in arbitrary order within the code.
3. All snippets should be auto-refreshable by reflecting any changes made to the source code. They should follow any source code changes such as moving code around, changing names, etc.

After pondering how I can implement this in as simple a fashion as possible, I've converged on the following design:

1. Label the start of a snippet with a tag marked by rarely-used delimiters, such as &|tag|&.
2. Auto-generate these tags when the documentation file is edited then saved.
3. Auto-refresh all snippets when the documentation file is opened by matching source code tagged snippets with their tagged snippets in the documentation file.

I've chosen Microsoft Word as a word processor and begun writing code in VBA (Visual Basic for Applications), Word's macro language. There's little good documentation on the language I've found; the built-in help is poor, MSDN lacks in many areas, and even searching the web produces mediocre results. I may purchase a book to help. I haven't found a good unit-testing framework for Word; a framework for Excel seems fairly tied to that platform.

So far, I've written code that divides a source file into named snippets; not bad progress, but there's much more to do. I should probably next:

1. Write unit tests, which I should have done first.
2. Create a good, high-level document to describe all this in more detail.

Visual Basic for Applications

The ideal for documentation creation

I find that the type of documentation I want to write isn't well supported by the tools I've found. In particular, I typically like to write documentation at three levels. First, there should be a high-level overview, defining the overall purpose and ideas behind a module of code. This should be followed by detailed description of every element in a source file. Finally, I'd like to provide a line-by-line commentary of each function, commenting on the particulars of its implementation. This documentation should, as necessary, include equations, diagrams, images, flow charts, videos, etc. Because code changes frequently, all code snippets or references to names within the code should be easily refreshed by applying a tool.

I see variants of this approach in use for several types of documentation. I typically write code for other programmers, rather than end users. Therefore, my "users" will be fellow programmers desiring to make use of a module I've created. For these users, a high-level explanation of a given header file followed by a description of each element of the header, provides all the information they need to make use of the module. For fellow developers, I'd like to present the same high-level overview, this time focusing of the algorithms used to implement elements declared in the header. This information naturally belongs with the source file the header accompanies. Next, a per-element detailed description of the source file might also be accompanies by a line-by-line analysis of some of the subtle portions of the code. (On a side note, I'd like to use this to develop and updated version of the PIC24 book I co-authored).

My dream implementation would be seamless: a fully-featured word-processing program in which I can type code or in-line documentation, including snippets of code in explanatory sections as necessary. All documentation would be transparently encoded in the raw source file. No such tool exists, to the best of my knowledge.

Existing tools

There's nothing new under the sun, including this idea. Its best-known formulation, Literate Programming by none other than Donald Knuth, "regards a program as a communication to human beings rather than as a set of instructions to a computer. Your program is also viewed as a hypertext document, rather like the World Wide Web." (from an associated site). While WEB (Knuth's tool) operates on Pascal to produce TeX documents, a more modern version (CWEB) applies the same process to C. The literate programming site provides additional information on these ideas; several other notable implementations (FunnelWeb, Noweb). The practical result (here's a sample of some code) is that a program is written in CWEB syntax (mixed C and TeX), then transformed to either C or TeX, making it painful (IMHO) to either write documentation or develop code! While other tools (



My favorite documentation tool, which I've used for several years, is Doxygen. It excels at extracting documentation from code and producing a polished, nicely cross-referenced result -- the middle level (describing each element) of my documentation hierarchy. However, it contains several major flaws, IMHO:

1. There's no way to directly edit the resulting documentation. I often find a typo or other small correction when browsing through the documentation, which then requires that I dig up the corresponding source, edit it, recompile the docs, and check. This discourages quick fixes.
2. Writing high-level documentation is painful; editing text then compiling reminds me of all the evils of LaTeX without any of the helpfulness of word wrapping, TexWorks docs-to-source synchronization, or quick compilation.
3. There's no way to write line-by-line commentary for a detailed look at an algorithm.
4. Including non-textual media is painful.

Back to blogging

It's been a busy semester, but it's over now. I'm returning to blogging as a way to trying to be more organized and to share interesting things with others.

The first question: does this make any sense? Who really cares what my to-do list is? I like having a place to store hyperlinks, since that's where I keep a lot of my ideas. Hopefully, that will be helpful. I'll keep lists in my gmail tasks and see how that works.

Interesting things:

• The ideas behind the quantum leaps framework are excellent. The book introducing these concepts is excellent if you can survive the introductory chapter (the "fly-n-shoot" game isn't a very motivating example).
• An annoyance: the examples tend to compile and run in DOS mode on a free compiler. That's just not very appealing to me. It would be fun to "port" the framework to run under Python, since the framework is pure C, making it multi-platform.
• The framework doesn't include a library for a particular processor. That would be very helpful, since some of the implementation details aren't clear to me. I'm considering creating just such a library for the PIC24. There is a TCP/IP stack implementation, which looks interesting; perhaps a good starting point.
• The author's blog makes for very interesting reading.
• Get your Starkville weather updates from Doug Gillham, an excellent meteorologist. They're particularly helpful for severe weather (more tornadoes, anyone?).
• A book from the National Academies Press, The Future of Computing Performance: Game Over or Next Level?, gives a great explanation of why power limits growth in computing performance. High-performance computing = low power computing, which is a very different paradigm.
• NASA posted a draft of their robotics roadmap. Now, if I could only find the interest to actually read it...
• I'm still looking for a good platform for Intro to Robotics. Some good finds: either the Stinger or the Dagu Rover 5 look good. Both have encoders in addition to DC motors, wheel/tracks, and gearing. However, both probably draw more than 1A for the motors, so I'll need a beefier H-bridge. An L298 would work, but needs external diodes and doesn't seem breadboardable. It looks like there's a nice product with all the necessary parts. As a second alternative, there's the Sparkfun motor driver, which contains a micro to do the PWM.
• An amazing paper on what computer science really is. A lot of Biblical references also provide me with insights on how my faith can be expressed in an academic context.

Weekly meeting

This week:

1. Review the task list.
2. Next week's meeting canceled -- Dr. Jones traveling to Case Western.
3. Look through SVN, Dropbox files.
4. Clean and inventory the lab.

Organizational meeting

It's time to get the semester started! The agenda:

1. Introductions, group home page
2. Research overview
1. Dynamics for continuum robots
2. Desktop supercomputing
3. Alternative navigation
3. New student orientation
1. Policy -- get everyone started on training. Jacob - update policy page. Krishna - add link to library formatting zip files.
2. Make sure everyone is on e-mail list, has permissions to edit home page, task list, SVN. Dr. Jones -- add Quintin, Tommy, Jacob, Ankit (SVN). Get SVN path fixed for everyone else.
3. Look at thesis formatting.
4. Review software. Get everyone started on SVN. Dr. Jones to do -- find MathType old version.
5. Update the people page!
6. Discuss recommended courses.
4. Schedule weekly meeting times; look at the task list.
5. Lab: need to clean and inventory. Dr. Jones - card access for Steven, Ankit.
6. SVN, Dropbox need to clean up! 

Fun links

I've been focusing on staying up to date with my inbox, but my blog has fallen far behind. A bit of catch-up:

• I'm using Camtasia to create a series of videos for the "Digital approach to Bible study" Sunday School class I teach. The site uses Joomla, so I got to learn enough of that to post videos using a plugin. While the first two are just .mp4 files and therefore require Quicktime, I figured that uploading an extra file allows me to use the Flash player, which is much more widely supported.
• The Autonomous Robots blog is neat.
• Python(x, y) is great! I'm really liking it for my Intro to Robotics class. I certainly miss some features (a nice integrated debugger is one).
• I decided to have a bit of fun and purchase the original StarCraft. It is fun!