From ab59fadb397e3f3a300bcd4b0b0d2ea05d443ae7 Mon Sep 17 00:00:00 2001
From: Antoine Musso <hashar@free.fr>
Date: Wed, 1 Aug 2012 18:23:56 +0200
Subject: [PATCH] (bug 38492) let doxygen document variables

We are using '@var' to document our variables and class properties,
which is unfortunately not working since '@var' is really meant to
document a function or method.

The way to fix it is to use an input filter that will rewrite our PHP
source code to pretends variables are typed. Aka something like:

 /**
  * A title object
  * @var Title
  */
 var $title;

Will be made:

 /**
  * A title object
  * @var Title
  */
 Title $title;

That is incorrect PHP code but it is properly recognized by Doxygen.

This patch as a side effect, all variables and properties will end up
being documented in addition of type hinting.

Use a hack authored by Goran Rakic at:
	http://stackoverflow.com/a/8472180/276152

Change-Id: I4ead1bd1feace44496b45ed8c55f5e52c59e7694
---
 maintenance/Doxyfile         |  2 +-
 maintenance/mwdoc-filter.php | 13 +++++++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)
 create mode 100644 maintenance/mwdoc-filter.php

diff --git a/maintenance/Doxyfile b/maintenance/Doxyfile
index aeb2e9d932..e0868bfdcc 100644
--- a/maintenance/Doxyfile
+++ b/maintenance/Doxyfile
@@ -182,7 +182,7 @@ EXAMPLE_PATH           =
 EXAMPLE_PATTERNS       = *
 EXAMPLE_RECURSIVE      = NO
 IMAGE_PATH             =
-INPUT_FILTER           =
+INPUT_FILTER           = "php mwdoc-filter.php"
 FILTER_PATTERNS        =
 FILTER_SOURCE_FILES    = NO
 FILTER_SOURCE_PATTERNS =
diff --git a/maintenance/mwdoc-filter.php b/maintenance/mwdoc-filter.php
new file mode 100644
index 0000000000..75290f4ff4
--- /dev/null
+++ b/maintenance/mwdoc-filter.php
@@ -0,0 +1,13 @@
+<?php
+# Original source code by Goran Rakic
+# http://blog.goranrakic.com/
+# http://stackoverflow.com/questions/4325224
+
+# Should be filled in doxygen INPUT_FILTER as "php mwdoc-filter.php"
+
+$source = file_get_contents( $argv[1] );
+$regexp = '#\@var\s+([^\s]+)([^/]+)/\s+(var|public|protected|private)\s+(\$[^\s;=]+)#';
+$replac = '${2} */ ${3} ${1} ${4}';
+$source = preg_replace($regexp, $replac, $source);
+
+echo $source;
-- 
2.20.1