[Pmwiki-users] Quoting http:/.... from within code invoke by $DoubleBrackets

[Patrick R. Michaud]

On Sat, Jan 24, 2004 at 03:03:49PM +0100, Christian Ridderstr?m wrote:
> Ok, I found an answer by remembering something Patrick wrote about 
> release 0.5.27. The solution is to use the function Keep()
> --- it could use small comment IMHO. Perhaps something like this:
> [...]

A question about documentation in general--would it be better to
put comments like this in the code, or to put them in Wiki pages that
more fully describe the theory of operation behind PmWiki's internals,
and can be appropriately cross-linked and cross referenced with other
functions and Documentation pages?  The urls for the comments could even 
be embedded in the code itself for quick access (my terminal software
allows me to click on any URI to open it), as in

    // http://www.pmichaud.com/wiki/PmWiki/FunctionKeep
    function Keep($text) {
      ...
    }

or, perhaps to keep the PmWiki group a bit cleaner

    // http://www.pmichaud.com/wiki/PmWikiCode/Keep
    function Keep($text) {
      ...
    }

This would also allow the code comments to be more easily 
updated/modified/improved by others instead of having to be
completely managed by the code author(s).

Also, I find that comments interspersed throughout code can 
be difficult to read, much less maintain, and comments do add
length and slight processing overhead to the .php files.  I like
to keep things short.

If others want to start building comment pages in a PmWikiCode group on
pmichaud.com, please feel free to get started and I'll join in.  Also, 
I don't necessarily want to document *every* PmWiki internal function 
right away, but if a list of "key" functions is generated, I'll do my 
best to write the initial documentation for them and add the appropriate 
URI references to the code itself.

Also, the PmWikiCode group is probably where I'll put documentation of
the many variables used in PmWiki, which I think is probably at least as
important as documenting the code.  

Pm