How to document configuration directives

Not for 'how-to' coding questions but PHP theory instead, this forum is here for those of us who wish to learn about design aspects of programming with PHP.

Moderator: General Moderators

User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

How to document configuration directives

Post 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.
User avatar
Christopher
Site Administrator
Posts: 13596
Joined: Wed Aug 25, 2004 7:54 pm
Location: New York, NY, US

Post 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?
(#10850)
User avatar
Ollie Saunders
DevNet Master
Posts: 3179
Joined: Tue May 24, 2005 6:01 pm
Location: UK

Post 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.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Post by Weirdan »

Image make your config class generate that docs for you
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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"?)
jamiel
Forum Contributor
Posts: 276
Joined: Wed Feb 22, 2006 5:17 am
Location: London, United Kingdom

Post 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.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Post 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 :)
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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.
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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?
Last edited by Ambush Commander on Fri Aug 11, 2006 7:54 am, edited 1 time in total.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Post 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?
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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.
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Post 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).
User avatar
Ambush Commander
DevNet Master
Posts: 3698
Joined: Mon Oct 25, 2004 9:29 pm
Location: New Jersey, US

Post 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)
User avatar
Weirdan
Moderator
Posts: 5978
Joined: Mon Nov 03, 2003 6:13 pm
Location: Odessa, Ukraine

Post by Weirdan »

No no, you're perfectly right :)
User avatar
Ollie Saunders
DevNet Master
Posts: 3179
Joined: Tue May 24, 2005 6:01 pm
Location: UK

Post by Ollie Saunders »

OT sorry:
AC wrote:

Code: Select all

var
Why have you choosen to write this for PHP 4?
Post Reply