doc/doxygen: tools to check documentation

doc/doxygen/dev/checkDoc.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+x=$(grep ingroup chapters/api/*|awk -F':' '{print $2}'| awk 'NF != 2')
+if test -n "$x" ; then
+    echo Errors on group definitions
+    echo $x
+fi
+
+echo
+echo "Defined groups"
+grep ingroup chapters/api/*|awk -F':' '{print $2}'| awk 'NF == 2'|sort|uniq
+echo

doc/doxygen/dev/starpu_check_documented.py

@@ -0,0 +1,38 @@
+#!/usr/bin/python
+
+import os
+
+class bcolors:
+    FAILURE = '\033[91m'
+    NORMAL = '\033[0m'
+
+def loadFunctionsAndDatatypes(flist, dtlist, fname):
+    f = open(fname, 'r')
+    for line in f:
+        mline = line[:-1]
+        if mline.count("\\fn"):
+            if mline.count("fft") == 0:
+                func = mline.replace("\\fn ", "")
+                flist.append(list([func, fname]))
+        if mline.count("\\struct ") or mline.count("\\def ") or mline.count("\\typedef ") or mline.count("\\enum "):
+            datatype = mline.replace("\\struct ", "").replace("\\def ", "").replace("\\typedef ", "").replace("\\enum ","")
+            dtlist.append(list([datatype, fname]))
+    f.close()
+
+functions = []
+datatypes = []
+
+for docfile in os.listdir('chapters/api'):
+    if docfile.count(".doxy"):
+        loadFunctionsAndDatatypes(functions, datatypes, "chapters/api/"+docfile)
+
+for function in functions:
+    x = os.system("fgrep -l \"" + function[0] + "\" ../../include/*.h ../../mpi/include/*.h ../../starpufft/*h ../../sc_hypervisor/include/*.h > /dev/null")
+    if x != 0:
+        print "Function <" + bcolors.FAILURE + function[0] + bcolors.NORMAL + "> documented in <" + function[1] + "> does not exist in StarPU's API"
+
+for datatype in datatypes:
+    x = os.system("fgrep -l \"" + datatype[0] + "\" ../../include/*.h ../../mpi/include/*.h ../../starpufft/*h ../../sc_hypervisor/include/*.h > /dev/null")
+    if x != 0:
+        print "Datatype <" + bcolors.FAILURE + datatype[0] + bcolors.NORMAL + "> documented in <" + datatype[1] + "> does not exist in StarPU's API"
+

doc/doxygen/dev/starpu_check_undocumented.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# Note: expects Coccinelle's spatch command n the PATH
+# See: http://coccinelle.lip6.fr/
+
+# StarPU --- Runtime system for heterogeneous multicore architectures.
+#
+# Copyright (C) 2011, 2012, 2013 Centre National de la Recherche Scientifique
+# Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
+#
+# StarPU is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 2.1 of the License, or (at
+# your option) any later version.
+#
+# StarPU is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+#
+# See the GNU Lesser General Public License in COPYING.LGPL for more details.
+
+stcolor=$(tput sgr0)
+redcolor=$(tput setaf 1)
+greencolor=$(tput setaf 2)
+
+H_FILES=$(find include mpi/include -name '*.h')
+
+functions=$(spatch -very_quiet -sp_file tools/dev/starpu_funcs.cocci $H_FILES)
+for func in $functions ; do
+	fname=$(echo $func|awk -F ',' '{print $1}')
+	location=$(echo $func|awk -F ',' '{print $2}')
+	x=$(grep "$fname(" doc/doxygen/chapters/api/*.doxy | grep "\\fn")
+	if test "$x" == "" ; then
+		echo "function ${redcolor}${fname}${stcolor} at location ${redcolor}$location${stcolor} is not (or incorrectly) documented"
+#	else
+#		echo "function ${greencolor}${fname}${stcolor} at location $location is correctly documented"
+	fi
+done
+
+echo
+
+structs=$(grep "struct starpu" $H_FILES | grep -v "[;|,|(|)]" | awk '{print $2}')
+for struct in $structs ; do
+    x=$(grep -F "\\struct $struct" doc/doxygen/chapters/api/*.doxy)
+    if test "$x" == "" ; then
+	echo "struct ${redcolor}${struct}${stcolor} is not (or incorrectly) documented"
+    fi
+done
+
+echo
+
+enums=$(grep "enum starpu" $H_FILES | grep -v "[;|,|(|)]" | awk '{print $2}')
+for enum in $enums ; do
+    x=$(grep -F "\\enum $enum" doc/doxygen/chapters/api/*.doxy)
+    if test "$x" == "" ; then
+	echo "enum ${redcolor}${enum}${stcolor} is not (or incorrectly) documented"
+    fi
+done
+
+echo
+
+macros=$(grep "define\b" $H_FILES |grep -v deprecated|grep "#" | grep -v "__" | sed 's/#[ ]*/#/g' | awk '{print $2}' | awk -F'(' '{print $1}' | sort|uniq)
+for macro in $macros ; do
+    x=$(grep -F "\\def $macro" doc/doxygen/chapters/api/*.doxy)
+    if test "$x" == "" ; then
+	echo "macro ${redcolor}${macro}${stcolor} is not (or incorrectly) documented"
+    fi
+done
+
+echo
+
+variables=$(grep --exclude-dir=.svn -rs -E "(getenv|get_env)" src/| tr ' ' '\012'|grep -E "(getenv|get_env)" | grep "\"" | sed 's/.*("//' | sed 's/").*//'|sort|uniq)
+for variable in $variables ; do
+    x=$(grep "$variable" doc/doxygen/chapters/environment_variables.doxy | grep "\\anchor")
+    if test "$x" == "" ; then
+	echo "variable ${redcolor}${variable}${stcolor} is not (or incorrectly) documented"
+    fi
+done
+

doc/doxygen/dev/starpu_funcs.cocci

@@ -0,0 +1,28 @@
+// StarPU --- Runtime system for heterogeneous multicore architectures.
+//
+// Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
+//
+// StarPU is free software; you can redistribute it and/or modify
+// it under the terms of the GNU Lesser General Public License as published by
+// the Free Software Foundation; either version 2.1 of the License, or (at
+// your option) any later version.
+//
+// StarPU is distributed in the hope that it will be useful, but
+// WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+//
+// See the GNU Lesser General Public License in COPYING.LGPL for more details.
+
+@starpufunc@
+position p;
+type t;
+identifier f =~ "starpu";
+@@
+
+t f@p( ... );
+
+@ script:python @
+p << starpufunc.p;
+f << starpufunc.f;
+@@
+print "%s,%s:%s" % (f,p[0].file,p[0].line)