wxruby users - Feb 2005 - New Docs - One and Three Quarter Look

Ok, the link:

http://www.mktec.com/dev_www/wxrubydocs/

(try http://www.mktec.com/dev_www/wxruby-docs/ ,it does not work for me, 
although this is the actual directory, could you email me privately if 
this does/doesn''t work for you, thx)

Updates in this preview of the new docs:
  - a new RDOC template courtesty of Nick
  - fixed paragraph jumping and monospace text where it shouldn''t be
  - added method arguments to rdoc output

Things left to do yet:
  - Scan for cpp names and change them to the corresponding ruby names 
(for classes, method, etc..) in descriptive text, and in methods arguments
  - Allow developers to add comments to the documentation

If you spot any bugs or things that look wrong please feel free to let 
me know. The docs will be added in the next release as well I do believe.

Zach

That''s awesome, Zach!  I really like Nick''s template; I agree
that it''s
much easier to work with.

A few things I noticed in the TextCtrl documentation:

1) There''s still a line in the class docs for TextCtrl that is 
monospaced and separated where it shouldn''t be.
2) There are some formatting codes still in there, like $\, $r, $n, 
\pythonnote{}, \perlnote{}
3) The code samples in the class docs don''t appear at all.  Not sure if
this is intentional.  I wonder if there might be a way of 
marking/identifying the code samples and having some way of replacing 
them with the equivalent Ruby code that one of us would write?  Like 
maybe have some extra code samples file that it uses to replace the C++ 
code.

Minor aesthetic note: the description at the top says: "This class 
documentation has automatically generated" -- should this be "was 
automatically generated"?

Thanks so much for your work on this.  It''s a huge help, and
it''s
looking great!

Marshall


On Feb 23, 2005, at 11:19 PM, Zach Dennis wrote:
> Ok, the link:
>
> http://www.mktec.com/dev_www/wxrubydocs/
>
> (try http://www.mktec.com/dev_www/wxruby-docs/ ,it does not work for 
> me, although this is the actual directory, could you email me 
> privately if this does/doesn''t work for you, thx)
>
> Updates in this preview of the new docs:
>  - a new RDOC template courtesty of Nick
>  - fixed paragraph jumping and monospace text where it shouldn''t
be
>  - added method arguments to rdoc output
>
> Things left to do yet:
>  - Scan for cpp names and change them to the corresponding ruby names 
> (for classes, method, etc..) in descriptive text, and in methods 
> arguments
>  - Allow developers to add comments to the documentation
>
> If you spot any bugs or things that look wrong please feel free to let 
> me know. The docs will be added in the next release as well I do 
> believe.
>
> Zach
> _______________________________________________
> wxruby-users mailing list
> wxruby-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
>

Some more things I''ve noticed as I''m browsing:

1) The new() methods don''t currently have arguments or a description
2) The docs for methods don''t currently include the documentation for 
what the parameters mean or what the return value is
3) The docs for methods don''t include the default value for arguments 
that have defaults (see Bitmap#save_file for example)
4) The class docs for controls (e.g. TextCtrl) don''t include the window
style or event handling sections.
5) The "In" and "Parent" lines at the top of each file
aren''t really
useful (especially Parent since it always says Object).  There should 
probably be a "Derived From" list like the WxWidgets docs instead.

One thing that''s much more of a feature request than a bug report: 
neither rdoc-generated docs nor the original WxWidgets docs list the 
methods that are defined by parent classes.  If I want to see all of 
the methods a given class supports, I have to manually click on every 
link for every parent class and every mix-in.  This is one thing I 
really miss from Javadoc.  If there were a way to list all the methods 
the class supports (perhaps in a section that links them to the parent 
class''s documentation, a la Javadoc), that would be a huge help.

Thanks again!

Marshall


On Feb 23, 2005, at 11:19 PM, Zach Dennis wrote:
> Ok, the link:
>
> http://www.mktec.com/dev_www/wxrubydocs/
>
> (try http://www.mktec.com/dev_www/wxruby-docs/ ,it does not work for 
> me, although this is the actual directory, could you email me 
> privately if this does/doesn''t work for you, thx)
>
> Updates in this preview of the new docs:
>  - a new RDOC template courtesty of Nick
>  - fixed paragraph jumping and monospace text where it shouldn''t
be
>  - added method arguments to rdoc output
>
> Things left to do yet:
>  - Scan for cpp names and change them to the corresponding ruby names 
> (for classes, method, etc..) in descriptive text, and in methods 
> arguments
>  - Allow developers to add comments to the documentation
>
> If you spot any bugs or things that look wrong please feel free to let 
> me know. The docs will be added in the next release as well I do 
> believe.
>
> Zach
> _______________________________________________
> wxruby-users mailing list
> wxruby-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
>

Marshall Elfstrand wrote:
> Some more things I''ve noticed as I''m browsing:
> 
> 1) The new() methods don''t currently have arguments or a
description
Ah yes, right now I''m just matching ruby methods to wx methods. I am
not
taking into account new() though with the constructor to the 
corresponding wx class. I will change this behavior to work how you 
mentioned.
> 2) The docs for methods don''t currently include the documentation
for
> what the parameters mean or what the return value is
Yes, I haven''t done anything with return values yet. And I am not 
display argument decscriptions because i was having rdoc formatting 
issues. There does not seem to be any good rdoc documentation anywhere 
online which doesn''t help either.
> 3) The docs for methods don''t include the default value for
arguments
> that have defaults (see Bitmap#save_file for example)
Yes I see what you''re saying. I will add this as well.
> 4) The class docs for controls (e.g. TextCtrl) don''t include the
window
> style or event handling sections.
Yep, I see this to. I''ll look into why it''s not being included
and get
it added. This may be another part though where there is rdoc formatting 
problems. If anyone is knowledgable in rdoc can assist I''d love to IRC 
or IM with you for just a few minutes one of these days!
> 5) The "In" and "Parent" lines at the top of each file
aren''t really
> useful (especially Parent since it always says Object).  There should 
> probably be a "Derived From" list like the WxWidgets docs
instead.
This is generic rdoc thing. I''m sure we can change this in the
template,
but I don''t know who we''re going for more, wxwindows
programmers using
ruby, or ruby programmers using wxruby? Consistency across other ruby 
libs use In/Parent.

> 
> One thing that''s much more of a feature request than a bug report:
> neither rdoc-generated docs nor the original WxWidgets docs list the 
> methods that are defined by parent classes.  If I want to see all of the 
> methods a given class supports, I have to manually click on every link 
> for every parent class and every mix-in.  This is one thing I really 
> miss from Javadoc.  If there were a way to list all the methods the 
> class supports (perhaps in a section that links them to the parent 
> class''s documentation, a la Javadoc), that would be a huge help.
I''ll start pondering this in my mind, and keep you posted if i come up 
with a viable solution =)

Thanks for the time you took to give this feedback,

Zach

On Feb 24, 2005, at 9:19 AM, Zach Dennis wrote:
>> 5) The "In" and "Parent" lines at the top of each
file aren''t really
>> useful (especially Parent since it always says Object).  There should 
>> probably be a "Derived From" list like the WxWidgets docs
instead.
>
> This is generic rdoc thing. I''m sure we can change this in the 
> template, but I don''t know who we''re going for more,
wxwindows
> programmers using ruby, or ruby programmers using wxruby? Consistency 
> across other ruby libs use In/Parent.
I would guess the audience is ruby programmers using wxruby (thus the 
desire for rdoc-style docs).  I was just thinking that currently the 
"In" field references a stub file -- as opposed to a source file that 
one could refer to for the inner workings of a method -- and the 
"Parent" field always says Object, which isn''t really
accurate in terms
of how the class functions.  If there''s a way of making these fields 
provide helpful information, great!  I just figured it would be easier 
to drop in the "Derived From" list from the WxWidgets docs.

I suppose the "In" field could list both the WxWidgets source file and
the wxruby source file, kind of like how the Array class lists multiple 
files in the core rdoc for the Ruby language.  I don''t know how 
difficult it is to do this in rdoc though.

Thanks!
Marshall

Nice work Zach. If you want, I can dig out the cpp name => ruby name out
of extractxml.rb for you. I know that we also have a giant ruby hash
table of object parents if that would be useful.

Do you know what rdoc uses to select it''s first page - can it be
something like a README? It would be nice to have a pretty first page.

Once again, looking great.

Nick
> Ok, the link:
> 
> http://www.mktec.com/dev_www/wxrubydocs/
> 
> (try http://www.mktec.com/dev_www/wxruby-docs/ ,it does not work for me, 
> although this is the actual directory, could you email me privately if 
> this does/doesn''t work for you, thx)
> 
> Updates in this preview of the new docs:
>   - a new RDOC template courtesty of Nick
>   - fixed paragraph jumping and monospace text where it shouldn''t
be
>   - added method arguments to rdoc output
> 
> Things left to do yet:
>   - Scan for cpp names and change them to the corresponding ruby names 
> (for classes, method, etc..) in descriptive text, and in methods arguments
>   - Allow developers to add comments to the documentation
> 
> If you spot any bugs or things that look wrong please feel free to let 
> me know. The docs will be added in the next release as well I do believe.
> 
> Zach
> _______________________________________________
> wxruby-users mailing list
> wxruby-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
> 
> 
--

On Feb 24, 2005, at 11:34 AM, Nick wrote:
> Do you know what rdoc uses to select it''s first page - can it be
> something like a README? It would be nice to have a pretty first page.
rdoc can have a --main option specified that tells it which page to use 
as its start page, which could just be a readme file.

Marshall

By the way, I was looking at the DC docs, and the method arguments 
appear to be in scrambled order.

Nick

Zach Dennis wrote:
> Ok, the link:
> 
> http://www.mktec.com/dev_www/wxrubydocs/
> 
> (try http://www.mktec.com/dev_www/wxruby-docs/ ,it does not work for me, 
> although this is the actual directory, could you email me privately if 
> this does/doesn''t work for you, thx)
> 
> Updates in this preview of the new docs:
>  - a new RDOC template courtesty of Nick
>  - fixed paragraph jumping and monospace text where it shouldn''t
be
>  - added method arguments to rdoc output
> 
> Things left to do yet:
>  - Scan for cpp names and change them to the corresponding ruby names 
> (for classes, method, etc..) in descriptive text, and in methods arguments
>  - Allow developers to add comments to the documentation
> 
> If you spot any bugs or things that look wrong please feel free to let 
> me know. The docs will be added in the next release as well I do believe.
> 
> Zach
> _______________________________________________
> wxruby-users mailing list
> wxruby-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
> 
> 
>

Nick wrote:
> 
> By the way, I was looking at the DC docs, and the method arguments 
> appear to be in scrambled order.
> 
Yeah I noticed that tonight to. That is fixed now and I''ll post another
link here shortly (either tonight or in the morning)

Zach

Ok another link: same one as before:

http://www.mktec.com/dev_www/wxruby-docs/
   -OR-
http://www.mktec.com/dev_www/wxrubydocs/

Changes:
  - defaults values were added to argument lists
  - arguments lists are now in the correct order

More to come tomorrow! Thanks for your patience,

Zach

Great work Zach on all of this!

At some appropriate point, you should check your doc tools in to CVS so that
we have a secure (and official) copy of them.

Curt
> -----Original Message-----
> From: wxruby-users-bounces@rubyforge.org
> [mailto:wxruby-users-bounces@rubyforge.org]On Behalf Of Zach Dennis
> Sent: Thursday, February 24, 2005 10:02 PM
> To: General discussion of wxRuby
> Subject: CVS for New Docs [was New Docs - One and Three Quarter Look]
>
>
> Ok another link: same one as before:
>
> http://www.mktec.com/dev_www/wxruby-docs/
>    -OR-
> http://www.mktec.com/dev_www/wxrubydocs/
>
> Changes:
>   - defaults values were added to argument lists
>   - arguments lists are now in the correct order
>
> More to come tomorrow! Thanks for your patience,
>
> Zach
> _______________________________________________
> wxruby-users mailing list
> wxruby-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
>
> --
> No virus found in this incoming message.
> Checked by AVG Anti-Virus.
> Version: 7.0.300 / Virus Database: 266.4.0 - Release Date: 2/22/2005
>

Curt Hibbs wrote:
> Great work Zach on all of this!
> 
> At some appropriate point, you should check your doc tools in to CVS so
that
> we have a secure (and official) copy of them.
> 
I''ve been trying to hold out so I can clean up my code =).
I''ll check
with Nick and see where he wants me to put them (i have more then 1 file).

Zach

Zach Dennis wrote:
>
> Curt Hibbs wrote:
> > Great work Zach on all of this!
> >
> > At some appropriate point, you should check your doc tools in
> to CVS so that
> > we have a secure (and official) copy of them.
> >
>
> I''ve been trying to hold out so I can clean up my code =).
I''ll check
> with Nick and see where he wants me to put them (i have more then 1 file).
Sure... I just wanted to mention this in case no had thought about it yet.

Curt

Marshall Elfstrand wrote:
> Some more things I''ve noticed as I''m browsing:
> 
> 1) The new() methods don''t currently have arguments or a
description
working on this...
> 2) The docs for methods don''t currently include the documentation
for
> what the parameters mean or what the return value is
working on this...
> 3) The docs for methods don''t include the default value for
arguments
> that have defaults (see Bitmap#save_file for example)
done...
> 4) The class docs for controls (e.g. TextCtrl) don''t include the
window
> style or event handling sections.
this is because i am parsing an xml file generated from the actual docs 
themselves, and the xml file includes a <windowstyles> tag with this 
information. Each style has it''s own <style> tag inside of
windowstyles.
   I can make this work for TextCtrl, but there are probably other 
classes with this type of information stored in differently named tags. 
I''m going to leave this out now, and I will start testing/modifying my 
parser to work with the docs from the wxWindows web site but after i get 
a little further along with the currenet docs.

If anyone has any ideas on this please let me know. Thanks,

Zach

Curt Hibbs wrote:
> Zach Dennis wrote:
> 
>>Curt Hibbs wrote:
>>
>>>Great work Zach on all of this!
>>>
>>>At some appropriate point, you should check your doc tools in
>>
>>to CVS so that
>>
>>>we have a secure (and official) copy of them.
>>>
>>
>>I''ve been trying to hold out so I can clean up my code =).
I''ll check
>>with Nick and see where he wants me to put them (i have more then 1
file).
> 
> 
> Sure... I just wanted to mention this in case no had thought about it yet.
Well since you mention it =). Nick (or Curt, or Kevin, whoever can tell 
me where to put it) where do you want my code to go?

Also, is the wxWindows-2.4.2.xml the file that stores wxWindows 
documentation that wxWindows builds their docs off of, or is it an 
extracted source from something else that we use. Marshall Elfstrand 
brought up a good point in an IM over the weekend regarding this, so I 
thought I''d check it out. Thanks,

Zach

Zach Dennis wrote:
> Also, is the wxWindows-2.4.2.xml the file that stores wxWindows 
> documentation that wxWindows builds their docs off of, or is it an 
> extracted source from something else that we use. Marshall Elfstrand 
> brought up a good point in an IM over the weekend regarding this, so I 
> thought I''d check it out. Thanks,
Unfortunately, the xml file is not the original source document for 
generating the wx docs. Hopefully eventually it will be, but currently 
the official text is maintained in TeX files. A guy created the xml file 
with that in mind, but the wx folks haven''t adopted it yet. Perhaps
with
the 2.5 version it could happen, if he tries and if other folks (like 
us) support him. Here''s his home page: 
http://www.bzzt.net/~wxwindows/index2.html

Kevin