Ive also been meaning for ages to write up how the error checkers work. I'll
try and do that between now and then end of the week.
Paul
----- Original Message -----
From: Paul Rogers
To: wtr-general@rubyforge.org
Sent: Tuesday, May 08, 2007 9:47 PM
Subject: Re: [Wtr-general] RDOC - Help determining what needs documentation
In my opionion, the rdocs are really dificult to read right now. I think if I
was picking up watir now and looking at the rdocs for the first time, Id be a
bit disheartened.
I would make sure that only relevant ( to the end user )
methods/classes/modules are in the rdoc
you can switch off rdoc like this
#--
# I dont get documented
def foo
end
#++
there are lots of methods that really dont help the user as far as
documenting them, eg element_tag ( Watir::xxx ) and the methods that people
would care about ( click , set etc ) are kind of hidden.
Id maybe also try to minimize the usage of the method descrioptions by making
a really good intro section ( see the rails docs, especially ActiveRecord::Base
( http://api.rubyonrails.org/classes/ActiveRecord/Base.html )
If you do a good intro maybe broken into
1- what watir is, ( license etc )
2 - finding objects using irb
- using show_xx abd xx.show methods, flash, to_s
3 - finding objects using :index, :value :class etc
4 - methods particular to several objects ( with links to the full list of
methods ) like
ie.link(:id, 'x').click
ie.button(:name , 'y').value
5 - then get into the rdocs like the rails docs do
Hope that helps
Paul
----- Original Message -----
From: Jeff Fry
To: wtr-general@rubyforge.org
Sent: Tuesday, May 08, 2007 8:06 PM
Subject: [Wtr-general] RDOC - Help determining what needs documentation
OK, I've learned (and documented on the wiki) how to: create a svn working
copy, edit the rdoc text, generate an rdoc using rake, and then generate a
patch file. There is of course a crucial step missing there...and that's
knowing what needs to be documented.
Brett and I had hoped that a way to find some of what needs documenting was
for me to read through his tagged Thunderbird archive of watir posts. After
some wrangling, I got the mail...but not the tags. >From this conversation on
the Thunderbird forums, it seems like the tags can't be transfered:
I'm left hoping we can find another way for me to learn what's been added
but not documented in v1.5. So Brett, Charley, Paul, or others involved in
building v1.5...if you were going to update the rdoc, how would you know what
to edit? If you were going to be making the edits yourself, what parts are most
time consuming for you? Would it be worth your time come up with a rough list
of things that need documentation and pass that to someone else to document? Or
does generating that list constitute the bulk of the work, after which there's
not much point in delegating the writing? Alternately, is there a way that you
could teach me to generate that list of things that needs documenting?
One specific example - how can I determine what methods can take :class as
a parameter? I know that this works for button, text_field and div...but is
there a way I can find out what other methods take :class via searching source
code in eclipse? I just tried reading & searching watir.rb for clues...but I
got lost.
I hope I can find a way through this last crucial step so that I can submit
a useful rdoc patch. If I manage to get or generate a list of to-dos, I can
still easily put a full day into editing the rdoc...but I'll need to do that
day between now and early this Friday. After that I'm away for a weekend and
then starting a new job, where I suspect I'll be too overwhelmed for a month or
two to contribute significantly.
Thanks,
Jeff
--
http://testingjeff.wordpress.com
----------------------------------------------------------------------------
_______________________________________________
Wtr-general mailing list
Wtr-general@rubyforge.org
http://rubyforge.org/mailman/listinfo/wtr-general
------------------------------------------------------------------------------
_______________________________________________
Wtr-general mailing list
Wtr-general@rubyforge.org
http://rubyforge.org/mailman/listinfo/wtr-general_______________________________________________
Wtr-general mailing list
Wtr-general@rubyforge.org
http://rubyforge.org/mailman/listinfo/wtr-general
