Forum OpenACS Improvement Proposals (TIPs): Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files.

Jeff, you make a good point.  Soon after I posted this TIP I realized breaking things up into two seperate tags would be the better way to do things.


I propose that we add two adp tags to the toolkit, one to handle a kind of ad_page_contract for adp files, and another to enable inline code comments.


This tag will be combine some functionalities from ad_page_contract and ad_proc.  There should only be one contract tag per adp file.  It should include a short description explaining what the adp is used for.  It should also contain attribute identifiers, including the following:

@author -- name and email address of the author.
@creation-date -- date of creation.
@cvs-id --  the expanding $Id$.
@arch-tag -- the unique arch identifier, for those using gnu-arch (tla).

@param -- used for each variable the adp expects, with the variable name and a description (see ad_proc documenation).

@css-class -- the name of the css class and a short description of how it is used.  This will make it easier for those modifying style sheets to know what classes they need to modify to obtain the look they want.


This tag will be used for inline code comments in the adp.  No special form is required for using this tag.

Both <contract> and <comment> tags and all of their contents will be removed as the adp is parsed and sent to the broswer.


I don't know how far you're willing to go with this, but...

If we're going to have a "contract" tag it would be good to make it "functional". Right now, there is no enforcement of tcl variable access from the adp. As in, you can declare a variable to be available from the tcl side, but the adp is not limited to the declared vars.

Of course, there should be some indication (switch) that the programmer/designer wants to apply this enforcement, otherwise many things would break.