Template:CodeCommentary/doc

Usage
Use the template to display blocks of code with syntax highlighting interspersed with blocks of commentary.

Additionally, you can add an icon next to a specific line of the code block, of an eye (indicating "look here!") or of a pointing hand (this may take a link; since we cannot directly add a link a class name in a code block, this is the next best thing.

And finally, you can add a block of not-quite-code with pre-style formatting (no line numbers, monospace font, etc) with an optional arrow icon next to a line.

To add a commentary block, do the following:

To add a code block with no icon, do the following (using the language of your choice from this list:

To add a code block with an eyes icon at line 3 in the block (counting from 1 always), do:

To add a code bloc with a hand icon at line 3 in the block and a link, do:

You may also change the line numbering to start with a different number, if you are spltting up a longer piece of code into blocks for commentary, as intended with this template. TO start a code block with line 5, do:

To add a block of ...stuff... with pre-style formatting and an arrow icon, use

Warnings
The syntax highlighter, or maybe it's MediaWiki, will toss leading blanks on the first and last lines of content of your code blocks. Stop this from happening by putting a zero-width-space (&amp;#8203;) as the first character of such a line.

You can use the template Template:ZWS to add one at the beginning of such lines.

You may also need to use Template:( to replace left curly brackets in some circumstances, or Template:)) to replace double right curly brackets.

Pre-blocks next to commentary blocks may be displayed with extra white space between them during an edit preview. After save they should look fine.

Examples
Do:

to get

{	"params": { "type": { "label": "Block type", "description": "\"code\" for a code block, \"commentary\" for a commentary block, \"pre\" for an unnumbered pre-style block", "type": "string", "default": "code" },		"content": { "label": "Block content", "description": "Content of a code commentary block, or code in the case of a code block", "example": "Here is some code commentary.", "type": "content" },		"pos": { "label": "Icon position", "description": "If an icon is specified, place that icon next to this line in the code block", "example": "3", "type": "number" },		"icon": { "label": "Icon", "description": "In a code block, \"eyes\" {eye icon) or \"hand\" (hand icon), in a pre block, \"arrow\" (arrow icon)",			"example": "eyes",			"type": "string"		},		"link": {			"label": "Hand link target",			"description": "In a code block, if \"hand\" is specified, it can be given a link target via this parameter.",			"example": "https://www.mediawiki.org",			"type": "url"		},		"lang": {			"label": "Block code language",			"description": "One of the languages known to the SyntaxHighlight extension",			"example": "python",			"type": "string"		},		"start": {			"label": "Start number of code block",			"description": "For code blocks, number the lines in this block starting from this number",			"example": "5",			"type": "number"		}	},	"description": "Display code blocks interspersed with blocks of commentary.",	"format": "block" }