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.
