mojombo / tomdoc

A flexible code documentation specification with human readers in mind.
333 stars 47 forks source link

Return values of shell functions #30

Open mlafeldt opened 13 years ago

mlafeldt commented 13 years ago

Hi,

I started using TomDoc for some shell scripts of mine and I really like it so far.

One thing I'm not entirely sure how to do best though is the Returns part.

In shell, it is common to have functions that return:

It's simple to document the first case with TomDoc's Returns line. But how to communicate the other cases?

(I guess writing to stdout to "return" strings is somehow unique to shell programming.)

sarahhodne commented 13 years ago

Maybe a "Prints" or "Outputs" section for the output, and use the "Returns" section for return codes?

mlafeldt commented 13 years ago

Yeah, but that would be a new section. I doubt it is really needed.

Or maybe I think too complicated. For example, I could simply use Returns for the actual return value and tell about echoed strings in the function description.

sarahhodne commented 13 years ago

That would work too. I guess that's what would happen if you, say, write a debug function which prints to STDERR in Ruby.

On 27 Oct 2011, at 23:18, Mathias Lafeldt reply@reply.github.com wrote:

Yeah, but that would be a new section. I doubt it is really needed.

Or maybe I think too complicated. For example, I could simply use Returns for the actual return value and tell about echoed strings in the function description.

Reply to this email directly or view it on GitHub: https://github.com/mojombo/tomdoc/issues/30#issuecomment-2549567

mlafeldt commented 12 years ago

FYI, I wrote a simple documentation generator for TomDoc'd shell scripts: https://github.com/mlafeldt/tomdoc.sh