On Apr 26, 2006, at 2:49 PM, Michael Koziarski wrote:
As I see it, the reason to "hide" the internal api, from at least
the main
api documentation, is that there are far more people interested in
working
*with* Rails than there are people interested in working *on*
Rails. For that
80 plus percent, having all the internal api docs mixed in with
the external
facing api would just be a huge jungle to sift through with a high
noise
ratio.
There could be some value, indeed, in having a separate place one
could go to
get full documentation, including the internal api, but I don't
think it's a
good fit for the main api docs.
Further to this, we've always said "If it isn't documented, then it
may change in the next release". There's probably a good case for
some articles explaining the internals of rails, as it makes it easier
for people to submit patches, and improves the quality of the patches,
making them easier to apply.
But if we document something in the API docs, people will use it. If
people use it, we can't change it without breaking their apps.
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
