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

Collapse
11: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 10)
Posted by Jeff Davis on 03/15/04 06:47 PM
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.

Collapse
12: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 11)
Posted by Benjamin Bytheway on 03/18/04 06:52 PM
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.

Collapse
21: Re: TIP #54 (Proposed) Add an adp tag to handle documenting and commenting adp files. (response to 12)
Posted by Randy O'Meara on 03/19/04 07:07 AM
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.