[wxruby-users] Documentation changes?

[Alex Fenton]

David Peoples wrote:
> I'm embarrassed but willing to admit that I completely missed for a
> couple weeks the "wxRuby Overview" page of the documentation that
> explains the more ruby-like calling method with named arguments. I
> realized something was up when working through the examples, and finally
> found the relevant page when I knew it must be there.
>   

Thanks for the suggestion. I'm aware that quite a bit of the sample and 
tutorial code demonstrates a wxRuby style that's a bit dated, and could 
be simplified, but it gradually gets updated as someone finds the time.

On the wiki I created a new page with suggestions for wxRuby programming 
style, and linked it from the home page. Hopefully this will help people 
find the nicer options quicker:

http://wxruby.rubyforge.org/wiki/wiki.pl?StyleGuide

> I don't have that patch, but I do have a suggestion slightly more
> practical. I think every class description page could have a section
> near the top with a paragraph similar to this one taken from the
> "overview" page:
>   

Like Chauk-Mean, I'm not sure this is quite the way to go about it. 
Although it's good that we have pretty complete and accurate API 
reference, the documentation layout and linking could be much improved. 
It's something we're looking into for future development, but 
unfortunately there's no documentation system out there that really 
meets our requirement.

We settled on Textile as being reasonably easy to write and output, but 
it's not really a code documentation format. The formatting of code gets 
messy and the results aren't the best.

RDoc (in the ruby standard library) is too simplistic - for example, it 
doesn't support type annotations for method arguments, which is 
important in learning wxRuby. The developers seem unwilling to consider 
adding this. Docbook produces lovely docs, but is pretty painful to write.

cheers
alex