Paul Rogers wrote: > 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. To me there are three important profiles of users of the Rdoc:
1. Testers who are new to Watir and to Ruby and who need to know what methods and arguments are available. (These are the people who i think you are referring to as "end users"). A particular challenge for these users is that they may not have experience reading Rdocs and therefore need to have many of the rdoc conventions explained that other Ruby libraries don't bother with. One example of this is that the IE class includes the Container module and therefore many of the methods available are not in the rdocs for IE, but rather for Container. Experienced Ruby programmers will be able to find this in the rdocs without trouble. Another example is whether the doc for IE#button should indicate that the method returns an instance of the Button class (with a link to the Rdoc for that class)? I don't think we did this for Watir 1.4, but doing this might actually make it so that the methods people care about aren't hidden. But it means that they need to understand a little more about how Watir works. 2. Ruby programmers who know how to read Rdocs and understand object-oriented programming. In particular, i am reluctant to say that we should only document methods and classes that the users in the first profile are interested in, because these people will appreciate more detailed information. 3. Library developers. In particular i think of the WET developers and the FireWatir/SafariWatir developers. We need to provide extension API's to allow Watir classes to be used, sometimes selectively by these other libraries. This means giving some attention to what the extension API's are and marking which are published and stable and which should not be used (private, or practically so). Again, not documenting any of these does not sound like a great idea. It is possible to specify which classes you want to generate RDOC for. One possibility would be to build a set of rdoc output (html) for the tester-user and then build another, more comprehensive collection for the serious developer. > 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 Personally, i no longer tell people to use the show_methods. Instead, i tell them to use the Dom Explorer. In fact, we have a number of reported bugs with the show methods, no unit tests for them, and no one seems to be maintaining them. I am considering removing them from Watir 1.6. (I haven't decided yet.) > 3 - finding objects using :index, :value :class etc One of the problems with the existing doc is that this information is repeated in too many places, and therefore has not been updated in too many places. > 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 At moment i am thinking that the doc for IE#link should point to the Link class and that the Link class should provide a summary of the most popular methods (as well as the detailed list which is automatically generated.) Another idea would be steal from the watir cheat sheet. http://secretgeek.net/watir_cheatsheet.asp Bret _______________________________________________ Wtr-general mailing list [email protected] http://rubyforge.org/mailman/listinfo/wtr-general
