I'm not on ruby-talk at the moment so I'm not copying to there.
Feel free to copy it if you wish.
On Tue, 7 Jun 2005, Andrew Thompson wrote:
<Sorry for the crosspost, but I thought I might as well try to reach as many
people as I could :) >
Hello Everyone,
I've been toying with ruby for the last month or so and I've become a big fan
of the language. My only gripe is the documentation is, at best, patchy and
obtuse.
There probably needs to be more tutorial stuff, and for some things
documenting the methods doesn't make the big picture clear.
I'm thinking of a system that will allow people to edit/add documentation
from the web based on the existing rdoc and source code comments, and then
generate CVS patches based on those changes which we can then send for
inclusion into mainline.
Why? Editing the rdoc comments in the source code is probably
easier than using the web for this (better editor, easier to browse
code, etc), and creating patches is not difficult, it's just diff -u.
Or, maybe you are saying there needs to be a more formal statement
of how one submits documentation changes, so that people know how to
do that?
My basic plan is to have a php style manual http://www.php.net/manual/en/
generated from the rdoc comments, with the ability to have the documentation
maintained in a wiki based fashion, and have user comments along the lines of
the PHP manual. This way we lower the barrier to writing documentation, allow
I'm completely unfamiliar with PHP, so that means nothing to me.
What are the salient features?
What do you perceive as the barrier that needs to be lowered?
I don't think it is the interface, I think it is understanding the
code sufficiently to be able to document it. For example: I have
used racc in the past but saw it had almost no comments in the
source. I read through, trying to add some, and there was nothing
constructive that I coauld add because the method names were clear
enough, and I could not actually find the bit the processes the
command line args, so I could not see where to add general usage
comments. Clearly this a limitation imposed by my ability
to understand the source. It's mostly C so that's more difficult to
understand (structurally) than Ruby, but familiarity with extconf would
have helped.
users to comment with code samples or additional info, and hopefully increase
and improve the amount of documentation ruby has.
I'd imagine the system would work as follows
Checkout latest CVS ruby code
Which one? 1.9, 1.8.3, .... That's part of the problem.
Extract the Rdoc comments
They make sense in place, with the code.
[...]
And whenever we think we've made enough progress we can generate a CVS patch
to be merged into mainline. I think we'd probably maintain a 'frozen' and an
IMHO we need to keep docs and code up to date together, which is why
Rdoc pulls comments from code (which implies I'm not the only one
thinking this).
editable version of each item of documentation, the frozen is the one shown
to casual users and the one we use to generate CVS, the editable one is the
one contributors edit, and periodically one of the moderators would update
but who would do that? They'd have to look at another disparate
source of information.
the frozen version from the editable one. This way malicious edits don't
screw up the publically viewed documentation, and we can control when a
particular item of documentation goes into CVS. Users would have to
that's normally controlled by who has write access.
register/login to edit/add documentation.
I'd also think we could generate 'stubs' for undocumented functions when we
parse the code, and flag them as being empty and in need of documentation.
I think that's sufficiently visible now. Presumably you have a
reason for thinking it isn't? The Stdlib docs on
ruby-doc.org have items italicised that need to be doc'ed more.
The comments would probably be fairly straightforward, no registration
Wiki spam?
required. The PHP manual has some great comments that help a lot with common
problems people experience using that particular function. I think this would
be a valuable addition.
[...]
Now, I'm willing to take a stab at this (I'm not just talking), but I'd like
to throw this out there for ideas or comments or flames (stony silence aren't
quite as welcome or helpful) and to see if adyone else is interested in
I know that much of what I wrote above sounds very negative. It's
partly because I'm trying to understand your perception of the
problem. My perception is that:
Rdoc is good, but it currently has no maintainer. Therefore, the
points where it is less good, that people want changed already, are not
being fixed. There are problems with it as Lothar has pointed out,
and things it doesn't really document like call graphs so you can
easity see which methods use what. It currently uses frames and it
would be better, I think, if it made more use of CSS features for
scrolling and such.
I currently believe that if someone is committed to improving the
doc situation and has the time to do it, then getting a deep
knowledge of Rdoc and being prepared to do some maintenance on it
would probably be the most helpful thing one can do, at present.
After all, it is a tool that many Rubyists are using now, and it is
shipped with ruby now.
When you described documentation as obtuse, this may reflect the
lack on intentional structure coming through, how things should be
put together in use. It may also reflect the problems of "software
archeology" -- trying to understand code that has lain unused for a
good while. Tools that help with this would be good to have. Maybe
Rdoc is as good a platform for that as any. Let's face it, it is
very good at what it does already.
helping with this project. I'm relatively new to Ruby and I know nothing
about Ruby on Rails, but I'm confident it can be done. (Maybe not well, maybe
not quickly, but it can be done.)
That last is another reason why I'd prefer you to focus on rdoc if you
choose to pursue a project in this area.
Anyway, let me know your thoughts on this.
Andrew
Hope some of that is useful,
Hugh
|
