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.
For slow guys like me, I’d like to see the whole documentation updated
to include the “keyword parameter” calling method for every function in
every class. I know, a ton of work, where’s my patch?
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:
As of version 1.9.1, it is possible to use named keyword arguments to
specify constructor parameters in arbitrary order. The names of the
arguments can be got from the class documentation. Omitted arguments
will be given their default value. The above call could look like
text = Wx::TextCtrl.new(parent, :text => ‘some text’,
:style => Wx::TE_MULTILINE)
For a full description of the new calling style, see the
[wxRuby Overview]
Any comments?
What is the procedure for submitting patches to the wxRuby
documentation?
David Peoples
Hi David,
On Wed, Mar 11, 2009 at 6:00 AM, David Peoples
[email protected] 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.
For slow guys like me, I’d like to see the whole documentation updated
to include the “keyword parameter” calling method for every function in
every class. I know, a ton of work, where’s my patch?
FYI, in addition to constructors for Window and its subclasses, there
are 2 other methods that support named arguments :
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:
For the Window constructors, instead of duplicating the description in
each method of each class, a link to the wxRuby overview could be
sufficient.
What is the procedure for submitting patches to the wxRuby documentation?
This is described at :
http://wxruby.rubyforge.org/wiki/wiki.pl?DocumentingWxRuby
Note that since the release of wxRuby-2.0, there has been some
reorganisation in the subversion repository.
You should check out for the stable 2.0 branch :
http://wxruby.rubyforge.org/svn/branches/wxruby_2_0_stable
Cheers.
Chauk-Mean.
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
Alex F. wrote:
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
PS - I hope you like the updated layout for the wiki, comments welcome.
A big thank you to Chauk-Mean for providing us a much better looking
logo - a ruby-ish twist on the wxWidgets design.
alex