Guidance on documenting functions

[shazow]

What's the preferred style for documenting functions?

a() { # a does foo
    ...
}

# b does foo
b() {
    ...
}

c() {
    # c does foo
    ...
}

[elasticdog]

My preference is style B.

[progrium]

B, however, I usually have a reflection based description system where I say:

declare desc="This is what my function does"

Just inside the function. I even do this when I don't have that system in place. But if you have a long description, it would make less sense there.

[shazow]

Do we want to include a full example? Ideally with usage and other kinds of verbose stuff people might have. I've been using this style here https://github.com/shazow/dotfiles/blob/master/helpers.bash

# b does foo by performing baaz
# Example:
#     $ b quux
#     someoutput
b() {
    ...
}

Ideally something that parsing/extracting won't be too hard.

[progrium]

👍

[silopolis]

AFAIC, 'B' too, and going a little further with bashdoc.sh script:

http://wiki.sourcemage.org/bashdoc
https://github.com/eatnumber1/envbot/tree/master/tools/bashdoc

Used to have a bookmark to this script website but can't find it.
This is the first refs DDG returned me and it's not bad to see it used in a
complete bash project.

My 2 cts

Jérémie Tarot
http://about.me/silopolis

[ingkebil]

Sorry for bumping an old thread!

B, however, I usually have a reflection based description system where I say:

declare desc="This is what my function does"

Just inside the function. I even do this when I don't have that system in place. But if you have a long description, it would make less sense there.

I'm not familiar with a 'reflection based description system'. I've googled around, but don't seem to find anything that would enable me to use the desc declared inside a function. How does one go about using this?

[progrium]

@ingkebil Using declare -f gets you the source of a function, which you can then process as text. Here is a module with this little bit of code that gets us this kind of reflection: https://github.com/gliderlabs/glidergun/blob/master/src/fn.bash