« | Main | »

February 13, 2011

One gripe I have with 'clever' one liners we define at start up is that the documentation sucks. So, to turn down the suck dial, shdoc is a little utility to help document shell functions better. Namely, there's really one file -- shdoc.rb -- but there's a little more to allow bootstrapping a shdoc command. The idea is that you include inline documentation for shell functions that are created on login -- like rdoc, javadoc, ...

For example, I include a file ~/.functions that is included when I log into a shell, and this file contains the following definition: 
# Groups the output of wireshark packets into single blocks
# @example sniff "ip src facebook.com" | group_packets
function group_packets() {
    awk -F"   " '/^$/ {print} /^[0-9a-f]{4}/ {printf("%s",$2)}'
}
When I run shdoc.rb on this file, I can now use man to see what group_packets does. e.g.
% man group_package
I get the following:

shdoc-group_packets.png

This uses an example, but you can also add parameters for options, for example, consider this function: 
# Run tshark on "en1"
# @param options shark options
function sniff() {
    tshark -i "en1" "$@"
}
then
% man sniff
gives me the following:

shdoc-sniff.png

This is a work in progress, and by default all the files are written to ~/man/man1, but say you have a file named .functions that is run on start up, then I would copy shdoc.rb to ~/bin and add the following to my start up script: 
export MANPATH=$MANPATH:$HOME/man
if [ -f ~/.functions ]; then
    source ~/.functions;
    if [ ! -f ~/bin/shdoc.rb ]; then
      wget --no-check-certificate \
       https://github.com/spudtrooper/shdoc/blob/master/shdoc.rb \
       -o ~/bin/shdoc.rb;
    fi
    chmod +x ~/bin/shdoc.rb
    ruby ~/bin/shdoc.rb .functions;
fi


Posted by jeff at February 13, 2011 02:00 PM