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

Benjamin,

I agree very much we need this.

Do we need any info besides author, date, cvs-id?

Like which CSS classes are being used? Cumbersome, probably not necessary, easier to read the code to find out.

Or which properties from the Tcl file are used? Probably not, we (will) have that in the Tcl file's contract already.

Maybe which Tcl file the template was designed for, if the tcl and adp files are not named and located the same.

/Lars

I think we need two tags, one for comments and one for the "page definition". Also great would be if the page definition tag worked with developer support so that you could tell which .adp files were actually used in constructing the page. Of course we could add that to templating instead I guess but I like having cvs info as well.

As we use more .vuh files, nested masters, and includes it can become quite difficult to tell which .adp/.tcl pairs are being used.

I think the proposal should be a little more concrete but I would approve in any case.

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.

**TIP MODIFICATION**

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.

<contract>

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.

<comment>

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.

Benjamin,

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.