HaDoc

haDoc ? an example

An example of source file using haDoc documentation is show at Permissions extension#Hacking.

haDoc comments

haDoc comments are used by Prof. Ir Marc Meurrens (be) and his team when hacking source files (e.g. in PHP, C++, etc). This is absolutely not a standard or a widely approved convention. It's simply a way to help hackers appropriate the knowledge of the structure of their own files or files received from others. Comments are inserted to facilitate the reading, the printing and the use of tools such as sed, grep, diff, patch, etc.

haDoc uses a set of magic words written according to a standard pattern as to facilitate grep operations. Words are written in uppercase, with hyphens as separators. The prefix is two slashes, one space and one exclamation point.

haDoc and versioning management

haDoc is definitively not a tool for versioning management : it's simply a set of small conventions to help hackers to appropriate source file(s).

haDoc and phpDoc

haDoc is absolutely not a replacement for phpDoc. phpDoc deals with the documentation of PHP classes while haDoc deals with the understanding of files.

Typically, the behaviour of a method is well described by phpDoc and this kind of details is, generally, not the concern of haDoc :

* @return string validated email address

On the other side, the history of the patches is managed by haDoc and, generally, does not need to be known in the phpDoc documentation :

// !PATCH-MM-ISBN-VALIDATION-2005-07-14

Of course, there may be some overlap, e.g. for the above example :

* @version 2005-07-14

Also, details on some patched implementations may be introduced in the phpDoc documentation, presumably as internal's.

About the word haDoc

haDoc stays for hacker documentation or hacking documentation.

haDoc magic words are allways prefixed by the four characters : " // ! ". As a joke, haDoc also refers to (fr) captain Haddock, a well known belgian personnality :-) which expressions make a (fr) large use of " ! " and other ponctuations...

Commonly used haDoc magic words

• // !FILE : /wiki/includes/SpecialMonBoulot.php // the very first line of any file
• // !EOF : /wiki/includes/SpecialMonBoulot.php // the very last line of any file
• // !DEPENDENCIE's : files included
• // !GLOBAL's : outside the class(es)
• // !GLOBAL-VAR's :
• // !GLOBAL-FUNCTION's :
• // !CONSTANTS : define's
• // !CLASS : near { ...
• // !COSMIC (a PHP class that does not extend another class)
• // !END-OF-CLASS : just after } ....
• // !IV's : instance variables
• // !CT : constructor
• // !IM's : instance methods
• // !ACCESSOR's :
• // !GETTER's :
• // !SETTER's :
• // !SF's : static functions
• // !TODO : the word says all...
• // !HISTORY :
• // !VERSION : mw-1.4.6
• // !BUG :
• // !PATCH-XY-FOO-BAR-2005-07-14
• example : // !PATCH-MM-ISBN-VALIDATION-2005-07-14
• // !FIXME :
• // !FIXED :
• // !SEE-ALSO :

Of course, other magic words may be used...

Usage

As an example, on a diff file, or on a whole set of files, a search, or a grep, on // !PATCH-MM-ISBN will easely indicates where changes were made regarding the patch on ISBN number validation made by MM in july 2005.

The feature is especially usefull when you (or somebody else) previously patched a version x of a software and you then need to re-insert the modifications in a version x+n, or, more generally, when you need to manually merge several (sometimes incompatible) patches, revisions and upgrades provided by several authors.

The feature is also usefull when you want to print a summary of files. Here is an exemple of such output :

// !FILE : includes/SpecialPermissions.php
// !CLASS : Permissions // !INNER-CLASS
// !ANTI-CRASH : mediawiki stuff + version stuff
// !VERSION // !DVRM  :
// !CONFIG : default values (to be eventually modified before include) :
// !CONSTANT's : internal constants 
// !INIT : pre-init stuff processed because of an include_once in the LocalSettings.php file :
// !FUNCTION : wfSpecialPermissions()
	// !STEP-1 OF wfSpecialPermissions() : complete the messages that will be used :
	// !STEP-2  OF wfSpecialPermissions()  : hooks for logs : none...
	// !STEP-3  OF wfSpecialPermissions() : include what should be included :
	// !STEP-4  OF wfSpecialPermissions() : inner class definition(s) :
	// !CLASS: Permissions extends SpecialPage // !INNER-CLASS
		// !IV's : none
		// !CT
		// !IM's : instance methods
		// !IM : execute() // !OVRDN
			// !TODO : rely on $wgValidSpecialPagesFr to translate...
		// !SF's : begin static functions :
		// !SF : function BuildHtmlLink()
		// !SF : function BuildHtmlTable()
			// !STEP-1 OF BuildHtmlTable() : translate
			// !STEP-2 OF BuildHtmlTable()  : init
			// !STEP-3 OF BuildHtmlTable()  : build the 2 sets
			// !STEP-4 OF BuildHtmlTable()  : sort the 2 sets
			// !STEP-5 OF BuildHtmlTable() : it's now time to prepare the HTML output
			// !STEP-5-1 OF BuildHtmlTable() : HTML thead stuff
			// !STEP-5-2 OF BuildHtmlTable() : HTML tbody stuff
			// !STEP-6 OF BuildHtmlTable() : returns the HTML string
		// !SF : function Wiki_2_Html( $szwMessage )
		// !SF : function Translate($szOriginal)
		// !SF : end static functions :
	}  // !END_OF_CLASS : Permissions
	// !STEP-5 OF wfSpecialPermissions() : register, make sure this special page is known
} // !END-FUNCTION : wfSpecialPermissions()
// !EOF : includes/SpecialPermissions.php

Script

Within this section, it's assumed you use a Unix or GNU/Linux operating system (other systems may eventually (?) be usefull for other tasks (?), but developping or hacking under such systems is, anyway, not considered professional/serious by the author of the haDoc notation)

You may want to create a small script, with the unique statement :

cat $1 | grep "// \!" > $1.hadoc

Mind the backslash : if you don't know too much about Regular Expressions, just copy the line.

The above listing was obtained by running :

./haDoc.sh SpecialPermissions.php