[freeside-devel] Documentation

[Systems Administrator]

On Sun, 19 Oct 2003 ivan at 420.am wrote:

> On Mon, Oct 20, 2003 at 01:22:04PM +1000, Systems Administrator wrote:
> > 	Ok, let me try this in pieces, then:
> >
> > 1.	How are you with the idea of information that is read as a comment 
> > 	by Perl (ie. lines start with a hash), delimited by things like 
> > 	the begin and end tabledef?  I'm happy to junk the idea as soon as 
> > 	someone thinks of a better one.  If someone knows how to declare a 
> > 	POD section, but not use it to generate POD, that might be an 
> > 	idea.  Or we could even try to come up with some format that would 
> > 	work in POD too.  Or I suppose we could even use something strange 
> > 	from perldata: Text after __DATA__ but may be read via the 
> > 	filehandle "PACKNAME::DATA", where "PACKNAME" is the package that 
> > 	was current when the __DATA__ token was encountered.  
> 
> Barking up the wrong tree completely.  Trying to hide the data is not
> the objective here.

	Right.  I was thinking in the direction of having the 
auto-generator read the relevant portion of each file, and then quit.  But 
I'll quit barking, and we'll be alright :).  

> tablename.pm modules can declare their schema information in a variable,
> like their "table" subroutine, or as a (package) global.

	Ok, I'm fine with that.  Does that mean that the new fs_setup will 
use all the tablename.pm modules?  

> > 2.	Aside from how we encapsulate it (ie. 1 above), what would you 
> > 	prefer here?  Perl data structures?  SQL?  Something that works 
> > 	with POD?  Or some non-standard entirely new thing?  Or something 
> > 	else that I'm unaware of?  HTML?  XML?  
> 
> "Perl data structures".  Take a look at DBIx::DBSchema.  pretty_print
> and pretty_read are close, but probably need to use a hashref for each
> column instead of throwing six elements for each column into a giant
> array, and also need to be factored down into DBSchema/Table.pm so we
> can work with a structure for an individual table, not just for the
> whole schema.

	So, roughly, in agent::table, you'd have something like:

-----
$schema = {
	'name'		=> 'agent',
	'primary_key'	=> 'agentnum',
	'unique'      => [],
	'index'     => [ ['typenum'] ],
	'columns'     => [
		{
			'name'		=> 'agentnum',
			'type'		=> 'SERIAL'
			'description'	=> 'The primary key of the table'
		},
		{
			'name'		=> 'agent',
			'type'		=> 'varchar'
			'description'	=> 'The name of the agent'
		},
		{
			'name'		=> 'typenum',
			'type'		=> 'int'
			'description'	=> 'Type of the agent'
		},
		{
			'name'		=> 'freq',
			'type'		=> 'int'
			'null'		=> 'NULL',
			'description'	=> '(not implemented)'
		},
		{
			'name'		=> 'prog',
			'type'		=> '???'
			'description'	=> '(not implemented)'
		},
		{
			'name'		=> 'disabled',
			'type'		=> 'char'
			'null'		=> 'NULL',
			'length'	=> 1,
			'description	=> 'Indicates that this agent is disabled'
		},
		{
			'name'		=> 'username',
			'type'		=> 'varchar'
			'null'		=> 'NULL',
			'description'	=> 'The username of the Agent'
		},
		{
			'name'		=> '_password',
			'type'		=> 'varchar'
			'null'		=> 'NULL',
			'description'	=> 'The password that matches the \
						Agent's username'
		},
	]
}

foreach $field(@$schema->columns) {
	if(! defined($field->length)) { $field->length = 80; }
}
-----

	Also, did you have anywhere where you wanted the links between the 
tables documented?  And are you using PostgreSQL's views anywhere?  

	:)

-- 
Tim Nelson
Systems Administrator
Sunet Internet
Tel: +61 3 5241 1155
Fax: +61 3 5241 6187
Web: http://www.sunet.com.au/
Email: sysadmin at sunet.com.au