buildr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sander Sõnajalg <san...@cyber.ee>
Subject small API documentation suggestion
Date Tue, 17 Feb 2009 14:27:09 GMT


-------- Original Message --------
Subject: 	small API documentation suggestion
Date: 	Tue, 17 Feb 2009 11:31:36 +0200
From: 	Sander Sõnajalg <sander@cyber.ee>
To: 	dev@buildr.apache.org



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




Mime
View raw message