I just discovered a cute tool called pocco on github. Apparently pocco is the Python version of what is also known as docco, rocco, and (gasp) shocco out there. Quite the zoo really! :-D So what does it do? It parses Python source and separates comments from code. It then dumps everything into HTML with a little CSS, making the comments appear on the left lined up with the corresponding code on the right. Neato.
Or it is? What could this possibly be useful for? Comments in Python are not usually used for documentation: we have docstrings after all! But docstrings are not perfect, for example you can only (by "natural" means anyway) attach a docstring to a module or class or function: What about those globals over there? Do I really have to document them in the module docstring?
But I realized that something like pocco is actually useful in Python. After all, the documentation you put into a docstring should be concise and clean: it should say exactly what it needs to say for someone else to use your stuff, nothing else. Boring! What about all those humorous anecdotes you accumulate while you hack? What about false starts, things that others should be told about before they head down the same wrong way. And so on, and so forth. With pocco, you can use comments for commentary and docstrings for documentation yet extract and (nicely?) format both. How cool is that? :-D Let's just hope that pocco will leave docstrings alone for good...
The other use I could come up with is code handouts in programming courses. Often the comments I write in this context have more of a "let me take you by the hand and work this through with you" feeling. Reading them in a nicely formatted and syntax-highlighted way may be nicer for everyone involved. True, since all comments are extracted it's hard to "comment on comments" that way... But that's okay, at least for me. Now all I need for this second application is Java, C, and C++ support! :-D
No comments:
Post a Comment