How to document configuration directives
Moderator: General Moderators
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
How to document configuration directives
After much kicking and screaming, I've finally decided to make my configuration class fluent: allow arbitrary configuration values to be set and red using generic getters and setters.
This is all fine and dandy, but configuration is no good without documentation. I can't use Doxygen (my usual documentor) for this task, since that program's oriented towards programming source code, so I need to figure out where to put the documentation for configuration variables. And not just plain old hand-written HTML help files, something that can pushed around, reformatted, reorganized, etc, etc, etc. Also, making it all dynamic removes my ability to specify default values.
So... will it be XML? More PHP files? Some other format I've never heard of? It's a bit hard to do research in this field, since lots of mature PHP applications inherit code from the days when they'd just globalize everything (glares at MediaWiki). And, of course, the Google for "php configuration" turns up lots of stuff on php.ini.
This is all fine and dandy, but configuration is no good without documentation. I can't use Doxygen (my usual documentor) for this task, since that program's oriented towards programming source code, so I need to figure out where to put the documentation for configuration variables. And not just plain old hand-written HTML help files, something that can pushed around, reformatted, reorganized, etc, etc, etc. Also, making it all dynamic removes my ability to specify default values.
So... will it be XML? More PHP files? Some other format I've never heard of? It's a bit hard to do research in this field, since lots of mature PHP applications inherit code from the days when they'd just globalize everything (glares at MediaWiki). And, of course, the Google for "php configuration" turns up lots of stuff on php.ini.
- Christopher
- Site Administrator
- Posts: 13596
- Joined: Wed Aug 25, 2004 7:54 pm
- Location: New York, NY, US
- Ollie Saunders
- DevNet Master
- Posts: 3179
- Joined: Tue May 24, 2005 6:01 pm
- Location: UK
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
Erm, document each of the classes with the configuration they use?You have lots of inplicit and explicit requirements buried in you comments. What do you think is the simplest solution -- balancing all of the constraints you have placed on it?
Okay. Before the switch, the Config class would have all the possible configuration values:I'm confused.
Could you explain your requirements and possibly the context is greater detail please, AC. So as to unconfuse me.
Code: Select all
// determines how the classes array should be construed:
// blacklist - allow allow except those in $classes_blacklist
// whitelist - only allow those in $classes_whitelist
// when one is chosen, the other has no effect
var $attr_class_mode = 'blacklist';
var $attr_class_blacklist = array();
var $attr_class_whitelist = array();
// designate whether or not to allow numerals in language code subtags
// RFC 1766, the current standard referenced by XML, does not permit
// numbers, but,
// RFC 3066, the superseding best practice standard since January 2001,
// permits them.
// we allow numbers by default, although you generally never see them
// at all.
var $attr_lang_alpha = false;
// max amount of pixels allowed to be specified
var $attr_pixels_hmax = 600; // horizontal context
var $attr_pixels_vmax = 1200; // vertical contextThe simplest solution, as arborint suggests (I think) is to just move the documentation from the configuration class to the respective classes that use the configuration. That decentralizes the configuration docs, which may be a good (or a bad) thing.
Maybe I'd like something like Apache's directive documentation...
Well, I'm not sure that would be a good idea. Maybe in a seperate ConfigDocumentor class (but basically this means "write your own"?)make your config class generate that docs for you
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
Most of the Config wrappers I've seen out there allow a choice between PHP, INI and XML formats, so that's not really a problem. However, keeping with Apache, the comments in the files aren't the only way of documenting configuration options and plus, one doesn't expect all the possible directives to be in a sample config file. Plus, it doesn't solve the problem of where one would define default.You could parse a .conf file which is the *nix way of doing configurations and comment it heavily. If a configuration option is commented out switch to Default.
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
Sorry, post phasing
Hmm... so the generator would look for special "configuration" comment-blocks in each of the classes in the application and then generate documentation based on that?yeah, why not? as long as you keep the syntax simple and follow certain format to make it simple to parse, it shouldn't be a problem. Just be lazy and don't reimplement Doxygen
Last edited by Ambush Commander on Fri Aug 11, 2006 7:54 am, edited 1 time in total.
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
Having explicit variables makes it easy to see what can be configured, but it also prevents extensions from adding any new configuration variables.Weirdan wrote:on the other hand, if you consider the documentation to be integral and very important part of configuration, why is it so wrong to embed it into config class?
Also, blobbing all the configuration docs together in one file isn't the most readable solution either.
- Ambush Commander
- DevNet Master
- Posts: 3698
- Joined: Mon Oct 25, 2004 9:29 pm
- Location: New Jersey, US
- Ollie Saunders
- DevNet Master
- Posts: 3179
- Joined: Tue May 24, 2005 6:01 pm
- Location: UK
OT sorry:
Why have you choosen to write this for PHP 4?AC wrote:Code: Select all
var
make your config class generate that docs for you