Jokes aside, I absolutely agree. I do think non-public (and non-generated) documentation would be extremely helpful. Often times it is a bit confusing reading the source code if there isn't a bit of a help. So writing comments on methods which are :nodoc: is still useful to those who are digging into the code for the first time or doing plugins. Someone writing a plugin might want to use something that's a bit more low level to keep their plugin as dry as possible and we should encourage that.
Having an active documentation writing spree as is suggested in this thread is absolutely a good idea for the public documentation. What I am suggesting is that we focus on this... If you change an "inner" method, write a line or two of method documentation. Just, while you're there writing your patch for some else, just snap in a few programmers notes.
If we all do that passively as we work on other stuff, then eventually we will have some smashingly good internal documentation for the project.
Thoughts?
-hampton
On 4/26/06, Jamis Buck <[EMAIL PROTECTED]> wrote:
I don't think the presence or absence of documentation ought to
indicate whether or not an API is published. The published API is
carved in stone. Any other API is subject to change without notice.
As long as we indicate which are part of the published API and which
are not, we're fine.
Regardless, lack of documentation is a bad thing, for any level of
the API.
- Jamis
_______________________________________________
Rails-core mailing list
Rails-core@lists.rubyonrails.org
http://lists.rubyonrails.org/mailman/listinfo/rails-core
_______________________________________________ Rails-core mailing list Rails-core@lists.rubyonrails.org http://lists.rubyonrails.org/mailman/listinfo/rails-core
