# Documentation changes?

**URL:** <https://www.ruby-forum.com/t/documentation-changes/162541>\
**Category:** wxRuby\
**Created:** [March 11, 2009, 6:08am UTC](https://www.ruby-forum.com/t/documentation-changes/162541 "2009-03-11T06:08:34Z")\
**Posts on this page:** 4\
**Page:** 1

<div class="post-metadata">

**Author:** ![David\_Peoples](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/f6c823/32.png) [@David\_Peoples](https://www.ruby-forum.com/u/David_Peoples)\
**Post date:** [March 11, 2009, 6:08am UTC](https://www.ruby-forum.com/t/documentation-changes/162541/1 "2009-03-11T06:08:34Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![David\_Peoples](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/f6c823/32.png) [@David\_Peoples](https://www.ruby-forum.com/u/David_Peoples)\
**Post date:** [March 11, 2009, 11:18am UTC](https://www.ruby-forum.com/t/documentation-changes/162541/2 "2009-03-11T11:18:37Z")

</div>

Hi David,

On Wed, Mar 11, 2009 at 6:00 AM, David Peoples  
[removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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/toolbar.html#ToolBar_additem)
- [http://wxruby.rubyforge.org/doc/sizer.html#Sizer\_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](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](http://wxruby.rubyforge.org/svn/branches/wxruby_2_0_stable)

Cheers.

Chauk-Mean.

---

<div class="post-metadata">

**Author:** ![David\_Peoples](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/f6c823/32.png) [@David\_Peoples](https://www.ruby-forum.com/u/David_Peoples)\
**Post date:** [March 12, 2009, 10:57pm UTC](https://www.ruby-forum.com/t/documentation-changes/162541/3 "2009-03-12T22:57:50Z")

</div>

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](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

---

<div class="post-metadata">

**Author:** ![David\_Peoples](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/d/f6c823/32.png) [@David\_Peoples](https://www.ruby-forum.com/u/David_Peoples)\
**Post date:** [March 12, 2009, 11:37pm UTC](https://www.ruby-forum.com/t/documentation-changes/162541/4 "2009-03-12T23:37:06Z")

</div>

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](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
