On Wed, 2007-02-07 at 23:44 -0600, James Bennett wrote: > (unrelated to the other message about documentation I just sent) [...] > One shining example is the _meta attribute on models -- there's useful > stuff in there, but unless you read the code or do some heavy-duty > introspection, you'll never learn about it. Using the dispatcher to > hook into various phases of the request/response cycle is another good > one -- we've got rudimentary documentation on the wiki, but it could > really stand to be cleaned up. > > I'd really like to make as much of that information as possible > accessible in "official" documentation -- we could start with anything > that has a declared-stable API, and build out as other things freeze > on the road to 1.0. > > Probably the best way to handle this would be a new documentation > section, which could include any necessary warnings about how using > these features will cause Django to drink all your beer, steal your > wife and kick your dog, but having documented "only use this if you > know what you're doing" features is, I think, better for consenting > Python adults than having undocumented "what the heck is this and am I > allowed to use it" features.
Generally, I'm in agreement with all this (after all, more documentation is always better). However, managing expectations is going to be a big part here -- as you address in the last paragraph -- because you seem to be talking about two different levels of API here. Stuff like the dispatcher and other "marked stable" items are very much exposed API, whereas _meta is internal and I wouldn't feel too comfortable with saying we are going to freeze it, since I know we have made a lot of changes over the past year in there as the implementation has been improved and fixed. My big concern here is that a lot of this internal stuff is always going to be potentially "unstable" unless we start feeling really brave/stupid. This is just because the way some problems are fixed is by changing the internals. Your plan seems sensible: let's make sure all the external stuff is documented. Let's also look at stuff that is on the boundary between internal and external -- an obvious one here is the Field class, since we've talked previously about making the necessary small changes to make it more easily sub-classable for models' purposes and should encourage people to do that. For things like _meta and db.core.loading (another semi-popular internal module that I know is going to have some change in behaviour prior to 1.0 in order to fix a couple of subtle but persistent bugs), maybe we can document how they work (slightly different from "how to use them") in a brief way and then try to keep that up to date. That was the approach I tried to take when documenting class construction in the wiki (the DevModelCreation page for those who are interested): no commitment to it always staying that way, but it at least describes what is happening for when you are debugging. Either way, some kind of overview about pieces of the machinery (a la DevModelCreation) is always going to useful, just for the curious. In fact, I wrote DevModelCreation partly for my own purposes, because my brain kept leaking out my ears trying to work it out each time I debugged stuff in there. Cheers, Malcolm --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Django developers" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/django-developers?hl=en -~----------~----~----~----~------~----~------~--~---
