[Maypole] Maypole::Config documentation

[Dave Howorth]

Sebastian Riedel wrote:
>>tables
>>------
>>This is mandatory, according to Maypole::Model::Base, so why is it 
>>described as 'if supported'?
> 
> We only only require classes(), tables() are optional.

So that's a documentation bug in Maypole::Model::Base.

>>table_to_class
>>--------------
>>This appears to be a private config variable used by 
>>Maypole::Model::CDBI::Plain in order to support the required class_of() 
>>interface method. As such:
>>- I don't see that it's view-related.
>>- I don't think it should be documented in the public interface of 
>>Maypole::Config.
>>- This is a clear example of the need for models etc to be able to 
>>extend the config state. I believe there should be a documented way for 
>>modules to do this, as I've said before. There are two reasons: (1) it 
>>means the people writing extensions can just get on and do it without 
>>worrying about unwanted side-effects etc. (2) it means the core 
>>developers know what other people are likely or not to do, and so can 
>>steer usage.
> 
> We don't use it, but there is a way:
> 
> package Maypole::Model::CDBI::Plain;
> Maypole::Config->mk_accessors(qw(table_to_class));

I suggest changing Maypole::Model::CDBI::Plain so it does use it, 
removing table_to_class from the config documents and code, and adding 
something like the following to the config doc:

=head2 Adding additional configuration data

If your modules need to store additional configuration data for their 
own use or to make available to templates, add a line like this to your 
module:

   Maypole::Config->mk_accessors(qw(variable or variables));

Care is needed to avoid conflicting variable names.


>>ok_tables
>>---------
>>the description is clearly incomplete but I have no idea when this 
>>method is supposed to be used, so I can't complete the description.
> 
> This is a hash representation of display_tables(), used as cache.

Then I'd suggest changing the description of display_tables and 
ok_tables as follows:

=head3 display_tables

This is a list of the tables that are public to your Maypole 
application. Defaults to all the tables in the database.

=head3 ok_tables

This is a hash of the public tables. It is populated automatically by 
Maypole from the list in display_tables and should not be changed.

Cheers, Dave