small API documentation suggestion

[Sander Sõnajalg <sa...@cyber.ee>]

Hi,

I found one quite confusing place in Buildr (1.3.3) API documentation 
and thought I would let you know, though it's really small and not so 
important. (It's more like i wanted to see how this contributing would 
work.. as i'm using Buildr now on daily basis, I'm likely to find some 
more serious things and issues, and it would feel good to help to 
improve your rather nice piece of software).

Anyway, in java/compiler.rb, the RDoc for module Compiler.

1) Documentation for :other is rather confusing and i was unable to 
guess it's usage before i read the source. I would suggest:

    # * :other       -- Array of options passed to the compiler. (Every 
separate word in the
    #   command line string intended to be given to javac should be a String
    #   element of it's own in this Array, e.g. to invoke "javac -encoding
    #   iso-8859-1", :other => ["-encoding", "iso-8859-1"] is the way to 
do it.)

2) (and the way the extra spaces are added to the documentation of 
:debug makes the RDoc somehow parse it incorrectly and looks really ugly 
in generated HTML.. see for your self: 
http://buildr.apache.org/rdoc/classes/Buildr/Compiler/Javac.html . It is 
okay when you delete those extra spaces:

    # * :debug       -- Generates bytecode with debugging information.  
Set from the debug
    #   environment variable/global option.




But thanks a lot for your work, we are now starting to use Buildr for 
our upcoming medicine project in our company.. it looks great so far :)

Greetings from Estonia!
Sander Sõnajalg

Re: small API documentation suggestion

[Alex Boisvert <bo...@intalio.com>]

On Tue, Feb 17, 2009 at 1:31 AM, Sander Sõnajalg <sa...@cyber.ee> wrote:

> 1) Documentation for :other is rather confusing and i was unable to guess
> it's usage before i read the source. I would suggest:
>
>   # * :other       -- Array of options passed to the compiler. (Every
> separate word in the
>   #   command line string intended to be given to javac should be a String
>   #   element of it's own in this Array, e.g. to invoke "javac -encoding
>   #   iso-8859-1", :other => ["-encoding", "iso-8859-1"] is the way to do
> it.)
>

Good point.  I've changed it to:

    # * :other       -- Array of options passed to the compiler
    # (e.g. ['-implicit:none', '-encoding', 'iso-8859-1'])

which illustrates multiple parameters, incl. one that requires two positions
on the command-line.

2) (and the way the extra spaces are added to the documentation of :debug
> makes the RDoc somehow parse it incorrectly and looks really ugly in
> generated HTML.. see for your self:
> http://buildr.apache.org/rdoc/classes/Buildr/Compiler/Javac.html . It is
> okay when you delete those extra spaces:
>
>   # * :debug       -- Generates bytecode with debugging information.  Set
> from the debug
>   #   environment variable/global option.
>

Fixed.

thanks!  (hope you enjoy buildr as much as we do!)
alex