[gobolinux-users] Gobo wants you! (to comment its scripts)

[Jonatan Liljedahl]

Michael Homer wrote:
> On Tue, Apr 8, 2008 at 4:25 AM, Benjamin Bruheim <grolgh at gmail.com> wrote:
>> Hi,
>>
>>  Python do have docstrings.
>>
>>  def foo():
>>   "This is a single line docstring"
>>   ....
>>
>>  def foo():
>>   """This is a multiline docstring
>>   Like this..."""
>>   ...
> Although that will work, there's a pretty strong convention to use the
> triple quotes for all docstrings, even the one-liners. PEP 257 covers
> what they're meant to look like:
> http://www.python.org/dev/peps/pep-0257/ (pretty thoroughly, really).
> For the how and why of the internals of a method, regular comments are
> still the right way to do it.
> 
> For the shell scripts just comments will have to suffice, but that'd
> be a pretty good way of structuring the function comments there too.

In my AlgoScore project I use comments in this form:

#:: == Score class ==[Score]
#:: The current score object is available as ``score`` in the console or
#:: ``me.score`` in classes.
#:: === Score.objects{} ===
#:: A table of all objects in the score, indexed by numerical ID.
var Score = {};
Score.init = func(o) {

And then I run it through a sed script (thanks Jonas!) like this:

    echo > $2
    sed -n 's/^#:: \(.*\)/\1/p;s/^#::[ \t]*$/\n/p' $1 >> $2

Which can then be processed with txt2tags to generate beautiful HTML.

Since it's exactly the same comment char as shell scripts, you could use
it straight away.

-- 
/Jonatan         [ http://kymatica.com ]