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

Christian Ridderström chr
Sat Jan 24 18:03:20 CST 2004


On Sat, 24 Jan 2004, Patrick R. Michaud wrote:

> 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:
> > [...]

About documentation:

In my experience, it doesn't work well to separate (low-level)
documentation from code :-( The best solutions I've seen so far (for
voluntary projects, i.e. nobody gets paid to do it) is to keep the
code-specific documentation next to the code and use some tool to
extract the documentation. Otherwise, you quickly end up with
documentation that is out of synch with the code base.

Now, even if you do document the purpose of every individual function
and variable next to their code, you *still* need additional
documentation that explains the purpose of the program, as well as the
strategy and structure behind its implementation. These are examples
of documentation that IMO is better placed separately, especially
since you often need to illustrate them using figures.

> 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) {
>       ...
>     }

As I wrote above, I think the code and documentation will quickly
diverge if we do it like this... When you make a change in the code,
you often don't feel like going to a separate place just to fix the
documentation.

> 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).

That *is* a good point, if nothing else, it takes a lot of work to
write and maintain documentation, so the more people that can
contribute the better. So, how about we introduce a special directive
that extracts documentation and code from the file pmwiki.php?
For example, let's say the code in pmwiki.php looks like this:

	// http://www.pmichaud.com/wiki/PmWikiCode/FunctionKeep
	/** Function: Keep
	Brief description of Keep using PmWiki-syntax.... ...
	*/
	function Keep($text) {
	 ...
	} // End Keep
	
and we introduce a directive like this:

	[[PHP-code:pmwiki.php Function=Keep]]

When the directive is parsed, it that would open 'pmwiki.php' and look
for '/** Function: Keep' and output:

	!!!Function @@Keep()@@
	Brief description of Keep using PmWiki-syntax.... ...

	 [=
	function Keep($text) {
	 ...
	}

The page containing this directive would then both show the brief
documentation next the code (which the author wrote), and allow
others to add comments. We could also look at tools like doxygen and
see if they could be used here.

> Also, I find that comments interspersed throughout code can 
> be difficult to read, much less maintain,

This really depends on what kind of comments we are talking
about. For instance:

* A *brief* description of the purpose of a program/script should go
  in the beginning of the file (assuming it's a one-file-program).  A
  more detailed description is probably better of as a separate
  document.

* A brief description of the purpose and interface of a function
  should be placed just before the function.

* Brief comments about actual implementation of a function belong inside
  functions IMO.

> and comments do add length and slight processing overhead to the
> .php files.

Do you have an idea of how much longer it takes to process pmwiki.php
if it's five times as big (because of comments)?

Well, using http://www.pmichaud.com/wiki/Cookbook/ExecutionTimer I
just tested it --- the result? The time difference was not measurable,
i.e.  it's less than the normal variation between runs (abt 2-3 ms).

No, the length and overhead is truly not important here. And if they
were, the solution would *not* be to avoid documenting the source, 
but to *strip* the comments to produce a "binary".

>  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.  

I'd say that documenting the purpose of a variable is a part of
documenting the code. In addition, and what I suspect you mean, it's
in PmWiki's case also very important to document the actual data,
i.e. the value of the variables.

Although, I wonder if maybe we should try and separate documentation
of the PmWiki markup language, from it's implementation?

/Christian



-- 
Dr. Christian Ridderstr?m, +46-8-768 39 44       http://www.md.kth.se/~chr




More information about the pmwiki-users mailing list