Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.

The codedoc plugin is directed at the display and documentation of blocks of code. The code can be of any type (i.e. language).

1. codedoc creates code blocks, either of file or code types, into which you can embed comments that support HTML markup, including both internal and external links.
2. it supports nested code blocks that can be toggled for display and hiding.

<codedoc code> 
   . . .your code here. . .
</codedoc>

<codedoc file> 
   . . .your code here. . .
</codedoc>

<codedoc toggle description> 
   . . .your code here. . .
</codedoc>

The first two forms create code blocks of the type specified by the parameter – code or file.

The third creates an initially hidden code block which comes with a toggle button enabling the block to be opened and closed (i.e.displayed and hidden). The description, which is a text string, describes the content of this block.

So, a more complete syntax model would be:

<codedoc code> 
 <codedoc toggle description> 
 </codedoc>
 <codedoc toggle description> 
 </codedoc>
</codedoc>

<codedoc file> 
 <codedoc toggle description> 
 </codedoc>
 <codedoc toggle description> 
 </codedoc>
</codedoc>

This nesting of the codedoc containers is limited to one level, that is you can't include a toggle inside another toggle.

Support for geshi highighting: To initiate the highlighting you must specify the language in the initial tag of the codedoc block, using a colon: code:php, code:java, etc.

<codedoc code:php> 
   . . .your code here. . .
</codedoc>

In the basic formatting, the code blocks are numbered (in square brackets). The numbering can be omitted by using the _no_numbers option:

<codedoc code:php _no_numbers> 
   . . .your code here. . .
</codedoc>

With codedoc you can add HTML formatted commentary to your code; these comments can contain links and therefore allow for cross-referencing. There are five syntax configurations. These are in fact independent of the codedoc containers, i.e. can appear anywhere on a page.

The first simply creates a timestamp for the file which contains the documented code:

~~codedoc:timestamp~~

This outputs the current user's name.

~~codedoc:user~~

The timestamp and the user name are independent of the codedoc container and can be placed anywhere in a document.

The second allows for internal comments on the code:

~~codedoc:comment~~             

The comment can contain DokuWiki internal links, for instance:

~~codedoc:DokuWiki embeds [[:snippet]] filenames in HTML definition lists [[:definitions#def_1|see definitions]]~~

As the above demonstrates, the links can contain references to internal link headings, that is to the named anchors which DokuWiki creates when it formats its H1-H5 headings.

One of the benefits of codedoc is that its comments support HTML markup. Comments will appear on more than one line if you insert HTML line-breaks into the comment or if the comment contains an internal newline. If the plugin finds an HTML line-break, i.e. <BR /> or <br />, or if the comment is on more than one line, the comment will have the multi-line comment format:

/*  
  comment
**/

Otherwise the comment will have the single line format:

/* comment */

In actual fact, the plugin looks only for the opening side of the markup, '<br' or '<BR'. It will not recognize mixed case, i.e. '<Br' or '<bR'.

An “internal newline” is a newline that occurs in the comment itself, where the text breaks and moves to a new line:

~~codedoc:This comment appears on more than one line
and so would be formatted as a
multi-line comment~~

The result would be:

/*
This comment appears on more than one line
and would be formatted as a
multi-line comment
**/

~~codedoc: <em>. . . </em>~~
~~codedoc: <b>. . . </b>~~

If the enclosed text contains either an <em> or a <b>, it is styled as defined in the plugin's style.css file. Currently, the colors will be red and the styling either bold or italic. The color can be anything you choose by making the change in style.css. The style.css file also has the option to treat either the em or the b as normal text, by uncommenting the relevant css. This is useful for emphasizing single words or phrases.

~~codedoc:xref:anchor_name~~

This will create a named anchor in your page, enabling you to link to places in your code, on the same or other pages, which are not marked by the anchors which DokuWiki creates¹⁾. This feature is obviously very useful when linking to places inside code blocks which cannot contain header markup and therefore cannot have anchors defined by DokuWiki headers.

~~codedoc:clean:text~~  

In order to support links in codedoc comments, the codedoc plugin must accept DokuWiki's substitution modes. Most of these are the various types of links that DokuWiki supports; in addition they include smileys, linebreaks (\\), acronyms and entities. If any of these are included in a codedoc code block, DokuWiki will make the appropriate substitution. In order to prevent substitutions where you want the literal text to remain in place, the codedoc plugin uses its clean text syntax. For instance, to prevent a smiley from being substituted for

8-) 

you would enter the following:

~~codedoc:clean:8-)~~

This is the equivalent of DokuWiki's double percent sign syntax:

%%8-)%%

codedoc higlights its comments in blue and outputs its literals in black. These can be changed in the style.css file, which contains the following styles:

.codedoc_hilite { color: blue; }
.codedoc_clean { color: black; }

• Updates version (2022-08-11 17:36)
• Updated for discontinued create_function in php 8 (2022-08-11 17:32)
• Corrected pType to block from normal (2018-04-20 18:49)
• fixed spacing around specials <em> and <b> (2018-04-20 17:33)
• Enabled emphasis and highlighting of individual wrods and phrases (2018-04-19 20:12)
• merged with geshi (2016-07-31 13:47)
• Merge branch 'master' of github.com:turnermm/codedoc into geshi (2016-07-31 13:34)
• Merge pull request #2 from splitbrain-forks/php7-signature (2016-01-22 17:56)
• Adjust method signatures to match parent (2016-01-22 17:30)
• tested for compatibility with Detritus (2015-10-06 15:25)
• tested for compatiblity with Detritus (2015-10-06 15:05)
• option to exclude numbering from show/hide headers (2014-10-18 12:02)