[freeside-devel] Documentation

[Systems Administrator]

On Sat, 18 Oct 2003 ivan at 420.am wrote:

> On Fri, Oct 17, 2003 at 10:46:27AM +1000, Systems Administrator wrote:
> > On Thu, 16 Oct 2003 ivan at 420.am wrote:
> > 
> > > On Thu, Oct 16, 2003 at 05:18:45PM +1000, Systems Administrator wrote:
> > > > 	Hi all.  I'm working on a better "table of contents" for the 
> > > > Schema reference.  How do I go about getting that included in the website
> > > 
> > > Email your patch here or directly to me, preferably as a unified diff
> > > (diff -u).  In the longer-term 1.5 timeframe, I'm want to get the schema
> > > reference to auto-generate from the documentation in the classes
> > > themselves.
> > 
> > 	Has any work on this auto-generation been done?
> 
> Nope.

	Ok, I'm intending to start on it, assuming my boss doesn't give me 
something else to do.  

> > If not, what format were you planning to embed the documentation in?  
> 
> Hadn't given it a whole lot of though yet.  Perhaps a data structure in
> each individual tablename.pm so we can autogenerate what freeside-setup
> needs too.

	Good idea.  The simplest way I can think of is:

# BEGIN tabledef
#    'agent' => {	# Table Descriptions
#      'columns' => [
#        'agentnum', 'serial',            '',     '',		# The primary key of the table
#        'agent',    'varchar',           '',     $char_d,	# The name of the agent
#        'typenum',  'int',            '',     '',
#        'freq',     'int',       'NULL', '',
#        'prog',     @perl_type,
#        'disabled',     'char', 'NULL', 1,
#        'username', 'varchar',       'NULL',     $char_d,
#        '_password','varchar',       'NULL',     $char_d,
#      ],
#      'primary_key' => 'agentnum',
#      'unique' => [],
#      'index' => [ ['typenum'] ],
#    },
# END tabledef

	Hopefully it doesn't get word-wrapped on me.  The basic idea is 
that we could suck this text from the file, s/^# //, and use it to 
generate fs_setup.  I could also use the same text to generate the 
documentation, the only problems being that:
1.	I would need the first thing on each "columns" line to be the 
	field name
2.	If we want word wrapping in our descriptions, I'd need to know 
	(otherwise the descriptions run off the side of the screen).  

	Another possibility would be this:

# BEGIN tabledef
#    'agent' => {
#      'description' => 'Table Descriptions'
#      'columns' => [
#        ['agentnum', 'serial',            '',     '',		
#		'The primary key of the table'],
#        ['agent',    'varchar',           '',     $char_d,	
#		'The name of the agent'],
#        ['typenum',  'int',            '',     ''],
#        ['freq',     'int',       'NULL', ''],
#        ['prog',     @perl_type],
#        ['disabled',     'char', 'NULL', 1],
#        ['username', 'varchar',       'NULL',     $char_d],
#        ['_password','varchar',       'NULL',     $char_d],
#      ],
#      'primary_key' => 'agentnum',
#      'unique' => [],
#      'index' => [ ['typenum'] ],
#    },
# END tabledef

	That would allow both the fs_setup and the documentation to be 
generated; it'd need a little more work to generate the fs_setup stuff 
(due to pulling all that stuff out of the arrays in "columns"), but it'd 
make the documentation easier, and probably be a neater solution all 
round.  

	Or did you have something entirely different in mind?  

-- 
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