Return values of shell functions

[mlafeldt]

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:

• a status code via return
• a string via echo or printf etc.
• both a status code and a string, e.g. exit status and matched lines returned by grep

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]

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

[mlafeldt]

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]

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]

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