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 <davidp at touringcyclist.com> 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 : - ToolBar#add_item - Sizer#add_item They are described in the overview part and the detailed part of the corresponding documentation page : - http://wxruby.rubyforge.org/doc/toolbar.html#ToolBar_additem - http://wxruby.rubyforge.org/doc/sizer.html#Sizer_additem> 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 Fenton 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?StyleGuidePS - 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