wxruby users - Feb 2005 - New Docs - One Look and a Partial Glance

Ok, same url as before:

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

We aren''t at the second look yet (because i dont'' have
arguments in the
docs yet), but that is coming. This fixes the bug where classes after 
Image didn''t have any docs, and this fixes the issue where many methods
weren''t documented (like the class Frame). Now the only methods that
are
not documented are those that don''t have a description. I was going to 
wait until it was all finished before showing everyone, but I couldn''t 
wait and I wanted to let the community know I wasn''t pulling their leg.
And this way I can get feedback before I get to far along with some of 
the ideas floating in my head.

Any more feedback you guys get would be great. Right now I''ve gathered:
  - put arguments and descriptions in rdoc
  - fix typo in header
  - convert cpp names in documented source into actual links using the 
ruby method, (ex: "WxApp::SetTopFrame" =>
"App::set_top_frame" )

I have some more possible ideas, but would like your feedback. I have 
the following information and I am thinking of adding it into the rdoc:

   - the lineno of the ruby method declaration, and the lineno of the 
declaration for the cpp that is assigned to it. would this be helpful or 
just confusing in the rdoc to say, "App.cpp line 543"?

   - Provide actual link to cpp documentation on 
http://www.wxwidgets.org and correspond classes and methods to their 
actual correpsonding wxwidgets.org page (perhaps this would make the 
above idea go away?)

   - Add the ability for a developer to add comments to a third-party 
file which my script will read in and add to the documentation.
   Example (say a file, addondocs.txt):
       Class: App
           method: set_top_frame
              description=<<-"ENDMETHOD"
                 set_top_frame can also be used in this manner. etc....
              ENDMETHOD

This would be done by running my script with a command line option or 
allowing the developer to manually enter information into the file, and 
it would check syntax of ''addondocs.txt''?

I don''t want to go overkill, but I want to really make these docs be
all
they can be. Nick, I''m taking guidance from you on this explicitly, so 
if you have any order or precedence for the docs, the template for rdoc, 
etc... just hollar. I dont'' want to get stuck if it isn''t in
the spot
you feel is most beneficial to the project.

I plan to work throughout the week on it as I get time. The next few 
days I have my sister visiting and a funeral to go to so I''ll do as
much
as I can, but it may not be much. =(

Thanks you all for your feedback, it is encouraging and guiding all at 
the same time, and I''m excited to get this docs polished and out there 
for the community to use.

Zach

This is great, Zach!  Thanks!

Yes, the arguments and descriptions would be useful (including the 
expected type and default parameters).  The only other thing I''ve 
noticed is that some of the docs (App.rb for example) jump between 
paragraph and preformatted text when it''s supposed to be all one 
sentence, which is rather jarring.  I gather that it''s some strange 
indenting in the original docs, so I don''t know how much that can be 
fixed up.

Line numbers wouldn''t help me personally, although linking to the C++ 
docs isn''t a bad idea.

Thank you again.  This is going to make a world of difference in the 
usability of the API.

Marshall


On Feb 8, 2005, at 8:37 PM, Zach Dennis wrote:
> Ok, same url as before:
>
> http://www.mktec.com/dev_www/wxruby-docs/
>
> We aren''t at the second look yet (because i dont'' have
arguments in
> the docs yet), but that is coming. This fixes the bug where classes 
> after Image didn''t have any docs, and this fixes the issue where
many
> methods weren''t documented (like the class Frame). Now the only 
> methods that are not documented are those that don''t have a 
> description. I was going to wait until it was all finished before 
> showing everyone, but I couldn''t wait and I wanted to let the 
> community know I wasn''t pulling their leg. And this way I can get 
> feedback before I get to far along with some of the ideas floating in 
> my head.
>
> Any more feedback you guys get would be great. Right now I''ve
gathered:
>  - put arguments and descriptions in rdoc
>  - fix typo in header
>  - convert cpp names in documented source into actual links using the 
> ruby method, (ex: "WxApp::SetTopFrame" =>
"App::set_top_frame" )
>
> I have some more possible ideas, but would like your feedback. I have 
> the following information and I am thinking of adding it into the 
> rdoc:
>
>   - the lineno of the ruby method declaration, and the lineno of the 
> declaration for the cpp that is assigned to it. would this be helpful 
> or just confusing in the rdoc to say, "App.cpp line 543"?
>
>   - Provide actual link to cpp documentation on 
> http://www.wxwidgets.org and correspond classes and methods to their 
> actual correpsonding wxwidgets.org page (perhaps this would make the 
> above idea go away?)
>
>   - Add the ability for a developer to add comments to a third-party 
> file which my script will read in and add to the documentation.
>   Example (say a file, addondocs.txt):
>       Class: App
>           method: set_top_frame
>              description=<<-"ENDMETHOD"
>                 set_top_frame can also be used in this manner. etc....
>              ENDMETHOD
>
> This would be done by running my script with a command line option or 
> allowing the developer to manually enter information into the file, 
> and it would check syntax of ''addondocs.txt''?
>
> I don''t want to go overkill, but I want to really make these docs
be
> all they can be. Nick, I''m taking guidance from you on this 
> explicitly, so if you have any order or precedence for the docs, the 
> template for rdoc, etc... just hollar. I dont'' want to get stuck
if it
> isn''t in the spot you feel is most beneficial to the project.
>
> I plan to work throughout the week on it as I get time. The next few 
> days I have my sister visiting and a funeral to go to so I''ll do
as
> much as I can, but it may not be much. =(
>
> Thanks you all for your feedback, it is encouraging and guiding all at 
> the same time, and I''m excited to get this docs polished and out
there
> for the community to use.
>
> Zach
> _______________________________________________
> wxruby-users mailing list
> wxruby-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
>

Zach,

The docs are looking great. When clicking around I came upon this in the
BusyInfo class:

    wxBusyInfo wait("Please wait, working...");
    for (int i = 0; i < 100000; i++)

It looks like you need to replace " , < and > with "
, < , >

In the HTML code they are showing up as &amp;quot; , &amp;lt; and
&amp;gt;

Keep up the good work.

Sean Long


-----Original Message-----
From: wxruby-users-bounces@rubyforge.org
[mailto:wxruby-users-bounces@rubyforge.org] On Behalf Of Zach Dennis
Sent: Tuesday, February 08, 2005 8:37 PM
To: General discussion of wxRuby
Subject: [Wxruby-users] New Docs - One Look and a Partial Glance


Ok, same url as before:

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

We aren''t at the second look yet (because i dont'' have
arguments in the
docs yet), but that is coming. This fixes the bug where classes after 
Image didn''t have any docs, and this fixes the issue where many methods
weren''t documented (like the class Frame). Now the only methods that
are

not documented are those that don''t have a description. I was going to 
wait until it was all finished before showing everyone, but I couldn''t 
wait and I wanted to let the community know I wasn''t pulling their leg.
And this way I can get feedback before I get to far along with some of 
the ideas floating in my head.

Any more feedback you guys get would be great. Right now I''ve gathered:
  - put arguments and descriptions in rdoc
  - fix typo in header
  - convert cpp names in documented source into actual links using the 
ruby method, (ex: "WxApp::SetTopFrame" =>
"App::set_top_frame" )

I have some more possible ideas, but would like your feedback. I have 
the following information and I am thinking of adding it into the rdoc:

   - the lineno of the ruby method declaration, and the lineno of the 
declaration for the cpp that is assigned to it. would this be helpful or

just confusing in the rdoc to say, "App.cpp line 543"?

   - Provide actual link to cpp documentation on 
http://www.wxwidgets.org and correspond classes and methods to their 
actual correpsonding wxwidgets.org page (perhaps this would make the 
above idea go away?)

   - Add the ability for a developer to add comments to a third-party 
file which my script will read in and add to the documentation.
   Example (say a file, addondocs.txt):
       Class: App
           method: set_top_frame
              description=<<-"ENDMETHOD"
                 set_top_frame can also be used in this manner. etc....
              ENDMETHOD

This would be done by running my script with a command line option or 
allowing the developer to manually enter information into the file, and 
it would check syntax of ''addondocs.txt''?

I don''t want to go overkill, but I want to really make these docs be
all

they can be. Nick, I''m taking guidance from you on this explicitly, so 
if you have any order or precedence for the docs, the template for rdoc,

etc... just hollar. I dont'' want to get stuck if it isn''t in
the spot
you feel is most beneficial to the project.

I plan to work throughout the week on it as I get time. The next few 
days I have my sister visiting and a funeral to go to so I''ll do as
much

as I can, but it may not be much. =(

Thanks you all for your feedback, it is encouraging and guiding all at 
the same time, and I''m excited to get this docs polished and out there 
for the community to use.

Zach
_______________________________________________
wxruby-users mailing list
wxruby-users@rubyforge.org
http://rubyforge.org/mailman/listinfo/wxruby-users

>  Nick, I''m taking guidance from you on this explicitly, so
 > if you have any order or precedence for the docs, the template for rdoc,
 > etc... just hollar. I dont'' want to get stuck if it
isn''t in the spot
 > you feel is most beneficial to the project.

I think you know what''s easiest at this point. I''ll go through
what''s
listed...

 >  - put arguments and descriptions in rdoc

This is pretty high up there.

 >  - fix typo in header

When you can fix it, fix it.

 >  - convert cpp names in documented source into actual links using the
 > ruby method, (ex: "WxApp::SetTopFrame" =>
"App::set_top_frame" )

That doesn''t bother me too much; it''s something that could be
corrected
later (see below)

 >   - the lineno of the ruby method declaration, and the lineno of the
 > declaration for the cpp that is assigned to it. would this be helpful or
 > just confusing in the rdoc to say, "App.cpp line 543"?


I think this would be confusing.

 >   - Provide actual link to cpp documentation on http://www.wxwidgets.org
 > and correspond classes and methods to their actual correpsonding
 > wxwidgets.org page (perhaps this would make the above idea go away?)

If the XML has that information, it would be helpful, but don''t break 
your back on it.

 >   - Add the ability for a developer to add comments to a third-party
 > file which my script will read in and add to the documentation.
 >   Example (say a file, addondocs.txt):
 >       Class: App
 >           method: set_top_frame
 >              description=<<-"ENDMETHOD"
 >                 set_top_frame can also be used in this manner. etc....
 >              ENDMETHOD

This is important to me. My personal dream would be to enable some sort 
of Wiki system on the docs, but that would take a ton of work. Really, 
some way for developers to edit the documentation is necessary, because 
the XML will have errors. (Making a documentation editor might be a good 
wxruby project...)

Other than that, my only issues are rdoc issues - why are all methods of 
the system listed? Why are all files listed? Why are those things at the 
top? My personal preference would be to stick the class list on the 
side, and leave the other two off. But that may start a holy war.

Once again, great work Zach.

Nick

Zach Dennis wrote:
> Ok, same url as before:
> 
> http://www.mktec.com/dev_www/wxruby-docs/
> 
> We aren''t at the second look yet (because i dont'' have
arguments in the
> docs yet), but that is coming. This fixes the bug where classes after 
> Image didn''t have any docs, and this fixes the issue where many
methods
> weren''t documented (like the class Frame). Now the only methods
that are
> not documented are those that don''t have a description. I was
going to
> wait until it was all finished before showing everyone, but I
couldn''t
> wait and I wanted to let the community know I wasn''t pulling their
leg.
> And this way I can get feedback before I get to far along with some of 
> the ideas floating in my head.
> 
> Any more feedback you guys get would be great. Right now I''ve
gathered:
>  - put arguments and descriptions in rdoc
>  - fix typo in header
>  - convert cpp names in documented source into actual links using the 
> ruby method, (ex: "WxApp::SetTopFrame" =>
"App::set_top_frame" )
> 
> I have some more possible ideas, but would like your feedback. I have 
> the following information and I am thinking of adding it into the rdoc:
> 
>   - the lineno of the ruby method declaration, and the lineno of the 
> declaration for the cpp that is assigned to it. would this be helpful or 
> just confusing in the rdoc to say, "App.cpp line 543"?
> 
>   - Provide actual link to cpp documentation on http://www.wxwidgets.org 
> and correspond classes and methods to their actual correpsonding 
> wxwidgets.org page (perhaps this would make the above idea go away?)
> 
>   - Add the ability for a developer to add comments to a third-party 
> file which my script will read in and add to the documentation.
>   Example (say a file, addondocs.txt):
>       Class: App
>           method: set_top_frame
>              description=<<-"ENDMETHOD"
>                 set_top_frame can also be used in this manner. etc....
>              ENDMETHOD
> 
> This would be done by running my script with a command line option or 
> allowing the developer to manually enter information into the file, and 
> it would check syntax of ''addondocs.txt''?
> 
> I don''t want to go overkill, but I want to really make these docs
be all
> they can be. Nick, I''m taking guidance from you on this
explicitly, so
> if you have any order or precedence for the docs, the template for rdoc, 
> etc... just hollar. I dont'' want to get stuck if it isn''t
in the spot
> you feel is most beneficial to the project.
> 
> I plan to work throughout the week on it as I get time. The next few 
> days I have my sister visiting and a funeral to go to so I''ll do
as much
> as I can, but it may not be much. =(
> 
> Thanks you all for your feedback, it is encouraging and guiding all at 
> the same time, and I''m excited to get this docs polished and out
there
> for the community to use.
> 
> Zach
> _______________________________________________
> wxruby-users mailing list
> wxruby-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
> 
> 
>

No need for anyone to reply to this, I just want to let you know I 
didn''t fall off the face of the earth in the last week. Had a funeral 
last weekend you can imagine the types of neat family fun and emotions 
that involves. I will be back going this weekend on finishing my docs 
upgrades.

thanks,

Zach

> No need for anyone to reply to this, I just want to let you know I
 > didn''t fall off the face of the earth in the last week. Had a
funeral
 > last weekend you can imagine the types of neat family fun and emotions
 > that involves. I will be back going this weekend on finishing my docs
 > upgrades.

It''s ok Zach - I just got hit with a bad case of the stomach flu, so my
productivity has been shot.

Nick

Zach Dennis wrote:
> No need for anyone to reply to this, I just want to let you know I 
> didn''t fall off the face of the earth in the last week. Had a
funeral
> last weekend you can imagine the types of neat family fun and emotions 
> that involves. I will be back going this weekend on finishing my docs 
> upgrades.
> 
> thanks,
> 
> Zach
> 
> _______________________________________________
> wxruby-users mailing list
> wxruby-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/wxruby-users
> 
> 
>