Page 1 of 3
How to document configuration directives
Posted: Thu Aug 10, 2006 10:54 pm
by Ambush Commander
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.
Posted: Fri Aug 11, 2006 12:37 am
by Christopher
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?
Posted: Fri Aug 11, 2006 4:05 am
by Ollie Saunders
I'm confused.
Could you explain your requirements and possibly the context is greater detail please, AC. So as to unconfuse me.
Posted: Fri Aug 11, 2006 4:12 am
by Weirdan

make your config class generate that docs for you
Posted: Fri Aug 11, 2006 7:27 am
by Ambush Commander
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?
Erm, document each of the classes with the configuration they use?
I'm confused.
Could you explain your requirements and possibly the context is greater detail please, AC. So as to unconfuse me.
Okay. Before the switch, the Config class would have all the possible configuration values:
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 context
These sorts of comments can easily be converted into docblocks and then parsed by PHPDocumentor or Doxygen. However, when the interface is made generic, you can't keep the documentation close to the code anymore.
The 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...
make your config class generate that docs for you
Well, I'm not sure that would be a good idea. Maybe in a seperate ConfigDocumentor class (but basically this means "write your own"?)
Posted: Fri Aug 11, 2006 7:39 am
by jamiel
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.
Posted: Fri Aug 11, 2006 7:50 am
by Weirdan
but basically this means "write your own"?
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

Posted: Fri Aug 11, 2006 7:50 am
by Ambush Commander
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.
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.
Posted: Fri Aug 11, 2006 7:52 am
by Ambush Commander
Sorry, post phasing
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
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?
Posted: Fri Aug 11, 2006 7:53 am
by Weirdan
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?
Posted: Fri Aug 11, 2006 7:56 am
by Ambush Commander
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?
Having explicit variables makes it easy to see what can be configured, but it also prevents extensions from adding any new configuration variables.
Also, blobbing all the configuration docs together in one file isn't the most readable solution either.
Posted: Fri Aug 11, 2006 7:58 am
by Weirdan
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?
exactly (I was thinking about single Config class though).
Posted: Fri Aug 11, 2006 7:59 am
by Ambush Commander
I was thinking about single Config class though
But wouldn't normal application functioning not need documentation generation? (or am I missing something, like the application passes the config class essential info for documentation)
Posted: Fri Aug 11, 2006 8:04 am
by Weirdan
No no, you're perfectly right

Posted: Fri Aug 11, 2006 8:14 am
by Ollie Saunders
OT sorry:
Why have you choosen to write this for PHP 4?