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

Jeff, what am I wrong about? That no one has come up with a reason to do this (the parsing part, not the commenting part)? That a contract tag is more expensive than a comment tag? But I guess if you don't have a hundred threads, it wouldn't be sourced as many times per server restart as that, but how many times per restart is the information needed for each visited page?

You could probably add an attribute switch which might avoid most of the cost, and provide some other benefits. I.e

<contract 
  log="Debug|Notice|Warning|None" 
  parsewhen="All|Admin"
>...
Tom,

I'm not proposing that the <contract> contents be parsed on every request.  In almost every case, the <contract> tag would be treated exactly the same as a <comment> tag.  Only in those cases where you were explicitely gathering documentation would the contents need to be parsed.

The reason for the seperate <contract> tag is to be able to identify a more easily parsable style, just like ad_page_contract does.

That no one has come up with a reason to do this (the parsing part, not the commenting part)?
Having some structured data is useful for the pages to be self documenting. Everywhere this is used is useful. We have ad_page_contract, comments on tables and columns in the datamodel, ad_library, and ad_proc documentation but no way currently to document in a structured way on the .adp side. I would think it's obviously a useful thing and I can come up with some more uses:
  • Defining an input contract which validates preconditions for the page (similiar to ad_page_contract)
  • All the stuff listed above with javadoc style tags
  • as a hook for per page testing (so you could synthesize the data required for input w/o needing the supporting tcl to run (so designers could work on a page before the code functions).
In any case, I think you want one heavy weight tag where the contents are held onto so you can do these fancy things, and a comment tag which is an immediate discard in the compiled function.
That a contract tag is more expensive than a comment tag?
The contract tag isn't particularly expensive. Certainly it is no more expensive than having an ad_page_contract documentation clause and likely cheaper than your version with the attributes (since I think a plain tag w/o attributes would parse quicker than one with but both are so fast that it's not material to debate them and I prefer free text for the contract). In terms of whether it's more expensive than a comment tag, in the comment tag when compiled the contents would be immediately discarded whereas with the contract tag, on a site where it was not simply discarded, it would need to put the contents into an nsv which for the proc_doc nsv_set (similiar size to the hypothetical nsv we would use for the contract tag) seems to take 9 microseconds per call as times in the ds shell on a fully loaded server (3736 procs defined with docs).
But I guess if you don't have a hundred threads, it wouldn't be sourced as many times per server restart as that, but how many times per restart is the information needed for each visited page?
You can make the exact same argument about ad_page_contract but I don't think many people are in favor of getting rid of the doc clause.
You could probably add an attribute switch which might avoid most of the cost, and provide some other benefits. I.e
<contract 
  log="Debug|Notice|Warning|None" 
  parsewhen="All|Admin"
>...
As mentioned above I doubt this would be faster in any material way and I expect it would be slower.