GNOME.org
 

gtk-doc r661 - in trunk: . tests tests/fail tests/fail/docs tests/fail/src

Author: stefkost
Date: Fri Jan 23 12:09:35 2009
New Revision: 661
URL: http://svn.gnome.org/viewvc/gtk-doc?rev=661&view=rev

Log:
	* gtkdoc-check.in:
	  No need to format a '\n' into a fromatstring.
	* gtkdoc-mkdb.in:
	  Add FIXMEs for Bug 568711.
	* gtkdoc-mkhtml.in:
	  Add a comment.
	* configure.in:
	* tests/Makefile.am:
	* tests/fail.sh:
	* tests/fail/Makefile.am:
	* tests/fail/docs/Makefile.am:
	* tests/fail/docs/tester-docs.xml:
	* tests/fail/docs/tester-sections.txt:
	* tests/fail/src/Makefile.am:
	* tests/fail/src/tester.c:
	* tests/fail/src/tester.h:
	  Add a test suite for failure checks.



Added:
   trunk/tests/fail/
   trunk/tests/fail.sh   (contents, props changed)
   trunk/tests/fail/Makefile.am   (contents, props changed)
   trunk/tests/fail/docs/
   trunk/tests/fail/docs/Makefile.am   (contents, props changed)
   trunk/tests/fail/docs/tester-docs.xml
   trunk/tests/fail/docs/tester-sections.txt   (contents, props changed)
   trunk/tests/fail/src/
   trunk/tests/fail/src/Makefile.am   (contents, props changed)
   trunk/tests/fail/src/tester.c   (contents, props changed)
   trunk/tests/fail/src/tester.h   (contents, props changed)
Modified:
   trunk/ChangeLog
   trunk/configure.in
   trunk/gtkdoc-check.in
   trunk/gtkdoc-mkdb.in
   trunk/gtkdoc-mkhtml.in
   trunk/tests/Makefile.am

Modified: trunk/configure.in
==============================================================================
--- trunk/configure.in	(original)
+++ trunk/configure.in	Fri Jan 23 12:09:35 2009
@@ -181,6 +181,9 @@
 tests/annotations/Makefile
 tests/annotations/src/Makefile
 tests/annotations/docs/Makefile
+tests/fail/Makefile
+tests/fail/src/Makefile
+tests/fail/docs/Makefile
 ])
 
 dnl run chmod on these after parsing them.

Modified: trunk/gtkdoc-check.in
==============================================================================
--- trunk/gtkdoc-check.in	(original)
+++ trunk/gtkdoc-check.in	Fri Jan 23 12:09:35 2009
@@ -78,7 +78,7 @@
 
 my $failed = ($total > 0) + ($undeclared != 0) + ($unused != 0);
 my $rate = 100.0*($checks - $failed)/$checks;
-printf '%.1f%%: Checks %d, Failures: %d%s', $rate, $checks, $failed, "\n";
+printf "%.1f%%: Checks %d, Failures: %d\n", $rate, $checks, $failed;
 exit ($failed != 0);
 
 sub Grep() {

Modified: trunk/gtkdoc-mkdb.in
==============================================================================
--- trunk/gtkdoc-mkdb.in	(original)
+++ trunk/gtkdoc-mkdb.in	Fri Jan 23 12:09:35 2009
@@ -311,13 +311,6 @@
     &ReadSourceDocumentation ($dir);
 }
 
-# FIXME: can we scan for a common prefix?
-# DEBUG
-# check $Declarations{$key} to first '_', we would need to count
-#my %prefixes = map { m/^(.*?)\_.*/;uc($1) => 1 } grep { m/\_/ } keys (%Declarations);
-#foreach (keys %prefixes) { print "$_\n"; }
-# DEBUG
-
 my $changed = &OutputSGML ("$ROOT_DIR/$MODULE-sections.txt");
 
 # If any of the DocBook SGML files have changed, update the timestamp file (so
@@ -335,17 +328,23 @@
             my $letter="";
             foreach my $symbol (keys(%IndexEntriesFull)) {
                 if(($NAME_SPACE eq "") || $symbol =~ /^$NAME_SPACE/i) {
-                    $letter=substr($symbol,$pos,1);
-                    if (defined($letter)) {
+                    if (length($symbol)>$pos) {
+                        $letter=substr($symbol,$pos,1);
+                        # stop prefix scanning
                         if ($letter eq "_") {
                             # stop on "_"
                             last;
                         }
+                        # Should we also stop on a uppercase char, if last was lowercase
+                        #   GtkWidget, if we have the 'W' and had the 't' before
+                        # or should we count upper and lowercase, and stop one 2nd uppercase, if we already had a lowercase
+                        #   GtkWidget, the 'W' would be the 2nd uppercase and with 't','k' we had lowercase chars before
+                        # need to recound each time as this is per symbol
                         $prefix{uc($letter)}++;
                     }
                 }
             }
-            if ($letter ne "_") {
+            if ($letter ne "" && $letter ne "_") {
                 my $maxletter="";
                 my $maxsymbols=0;
                 foreach $letter (keys(%prefix)) {
@@ -384,7 +383,8 @@
 #############################################################################
 # Function    : OutputObjectList
 # Description : This outputs the alphabetical list of objects, in a columned
-#		table. FIXME: Currently this also outputs ancestor objects
+#		table.
+#               FIXME: Currently this also outputs ancestor objects
 #		which may not actually be in this module.
 # Arguments   : none
 #############################################################################
@@ -3864,10 +3864,10 @@
             # merge parameters
 	    if ($symbol =~ m/.*::.*/) {
 		# For signals we prefer the param names from the source docs,
-	        # since the ones from the templates are likely to contain the
-	        # artificial argn names which are generated by gtkdoc-scangobj.
+		# since the ones from the templates are likely to contain the
+		# artificial argn names which are generated by gtkdoc-scangobj.
 		$SymbolParams{$symbol} = $SourceSymbolParams{$symbol};
-                # FIXME: we need to check for empty docs here as well!
+		# FIXME: we need to check for empty docs here as well!
 	    } else {
 		# The templates contain the definitive parameter names and order,
 		# so we will not change that. We only override the actual text.
@@ -3875,6 +3875,11 @@
 		if (!defined ($tmpl_params)) {
                     #print "No merge needed for $symbol\n";
                     $SymbolParams{$symbol} = $SourceSymbolParams{$symbol};
+                    #  FIXME: we still like to get the number of params and merge
+                    #  1) we would noticed that params have been removed/renamed
+                    #  2) we would catch undocumented params
+                    #  params are not (yet) exported in -decl.txt so that we
+                    #  could easily grab them :/
 		} else {
                     my $params = $SourceSymbolParams{$symbol};
                     my $j;
@@ -3966,23 +3971,34 @@
                     $type="SIGNAL";
                 }
 
-                #print "Check param docs for $symbol, tmpl_params: ",$#$tmpl_params,"\n";
+                print "Check param docs for $symbol, tmpl_params: ",$#$tmpl_params," entries, type=$type\n";
 
-                my $j;
-                for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) {
-                    # Output a warning if the parameter is empty and
-                    # remember for stats.
-                    my $tmpl_param_name = $$tmpl_params[$j];
-                    my $tmpl_param_desc = $$tmpl_params[$j + 1];
-                    if ($tmpl_param_desc !~ m/\S/) {
-                        if (exists ($AllIncompleteSymbols{$symbol})) {
-                            $AllIncompleteSymbols{$symbol}.=", ".$tmpl_param_name;
-                        } else {
-                            $AllIncompleteSymbols{$symbol}=$tmpl_param_name;
+                if ($#$tmpl_params > 0) {
+                    my $j;
+                    for ($j = 0; $j <= $#$tmpl_params; $j += $PARAM_FIELD_COUNT) {
+                        # Output a warning if the parameter is empty and
+                        # remember for stats.
+                        my $tmpl_param_name = $$tmpl_params[$j];
+                        my $tmpl_param_desc = $$tmpl_params[$j + 1];
+                        if ($tmpl_param_desc !~ m/\S/) {
+                            if (exists ($AllIncompleteSymbols{$symbol})) {
+                                $AllIncompleteSymbols{$symbol}.=", ".$tmpl_param_name;
+                            } else {
+                                $AllIncompleteSymbols{$symbol}=$tmpl_param_name;
+                            }
+                            &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
+                                "$item description for $symbol::$tmpl_param_name is missing in source code comment block.");
                         }
+                    }
+                }
+                else {
+                    if ($#$tmpl_params == 0) {
+                        $AllIncompleteSymbols{$symbol}="???";
                         &LogWarning (&GetSymbolSourceFile ($symbol), &GetSymbolSourceLine($symbol),
-                            "$item description for $tmpl_param_name is missing in source code comment block.");
+                            "$item descriptions for $symbol are missing in source code comment block.");
                     }
+                    # $#$tmpl_params==-1 means we don't know about parameters
+                    # this unfortunately does not tell if there should be some
                 }
             }
         }

Modified: trunk/gtkdoc-mkhtml.in
==============================================================================
--- trunk/gtkdoc-mkhtml.in	(original)
+++ trunk/gtkdoc-mkhtml.in	Fri Jan 23 12:09:35 2009
@@ -33,6 +33,8 @@
 
 if test $uninstalled = yes; then
       # this does not work from buiddir!=srcdir
+      # we could try this
+      # MAKE_SCRDIR=$(abs_srcdir) MAKE_BUILDDIR=$(abs_builddir) gtkdoc-mkhtml ...
       gtkdocdir=`dirname $0`
       #echo "uninstalled, gtkdocdir=$gtkdocdir"
 else

Modified: trunk/tests/Makefile.am
==============================================================================
--- trunk/tests/Makefile.am	(original)
+++ trunk/tests/Makefile.am	Fri Jan 23 12:09:35 2009
@@ -1,10 +1,10 @@
 ## Process this file with automake to produce Makefile.in
 
-SUBDIRS = gobject bugs annotations .
+SUBDIRS = gobject bugs annotations fail .
 
 if BUILD_TESTS
 
-TESTS = gobject.sh bugs.sh annotations.sh
+TESTS = gobject.sh bugs.sh annotations.sh fail.sh
 TESTS_ENVIRONMENT = \
 	PATH=$(abs_top_builddir):$(srcdir):$(PATH) \
 	PERL5LIB=$(abs_top_builddir):$(PERL5LIB)
@@ -12,5 +12,5 @@
 endif
 
 EXTRA_DIST = gtkdoctest.sh \
-	gobject.sh bugs.sh annotations.sh
+	gobject.sh bugs.sh annotations.sh fail.sh
 

Added: trunk/tests/fail.sh
==============================================================================
--- (empty file)
+++ trunk/tests/fail.sh	Fri Jan 23 12:09:35 2009
@@ -0,0 +1,23 @@
+#!/bin/sh
+
+dir=`dirname $0`
+suite="fail"
+DOC_MODULE="tester"
+failed=0
+tested=0
+
+cd $dir/$suite/docs
+
+echo "Running suite(s): gtk-doc-$suite";
+
+# tests
+# check missing section description
+grep >/dev/null "tester:Long_Description" $DOC_MODULE-undocumented.txt
+if test $? = 1 ; then failed=$(($failed + 1)); fi
+tested=$(($tested + 1))
+
+# summary
+echo "tested : $tested, failed : $failed"
+rate=$((100*($tested - $failed)/$tested));
+echo "$rate %: Checks $tested, Failures: $failed"
+exit `test $failed != 0`;

Added: trunk/tests/fail/Makefile.am
==============================================================================
--- (empty file)
+++ trunk/tests/fail/Makefile.am	Fri Jan 23 12:09:35 2009
@@ -0,0 +1,10 @@
+## Process this file with automake to produce Makefile.in
+
+SUBDIRS = . src docs
+
+if BUILD_TESTS
+
+check-local: clean
+
+endif
+

Added: trunk/tests/fail/docs/Makefile.am
==============================================================================
--- (empty file)
+++ trunk/tests/fail/docs/Makefile.am	Fri Jan 23 12:09:35 2009
@@ -0,0 +1,78 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=tester
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+DOC_SOURCE_DIR=$(top_srcdir)/tests/fail/src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=2>&1 | tee gtkdoc-scangobj.log
+
+# Extra options to supply to gtkdoc-scan.
+SCAN_OPTIONS=--deprecated-guards="GTKDOC_TESTER_DISABLE_DEPRECATED" \
+  --ignore-decorators="GLIB_VAR" \
+  2>&1 | tee gtkdoc-scan.log
+
+# Extra options to supply to gtkdoc-mkdb.
+MKDB_OPTIONS=--sgml-mode 2>&1 | tee gtkdoc-mkdb.log
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=2>&1 | tee gtkdoc-mktmpl.log
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=2>&1 | tee ../gtkdoc-mkhtml.log
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# --html-dir=$(HTML_DIR)
+FIXXREF_OPTIONS=--extra-dir=$(glib_prefix)/share/gtk-doc/html 2>&1 | tee gtkdoc-fixxref.log
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+HFILE_GLOB=$(top_srcdir)/tests/fail/src/*.h
+CFILE_GLOB=$(top_srcdir)/tests/fail/src/*.c
+
+# Header files to ignore when scanning.
+IGNORE_HFILES=config.h
+
+# Images to copy into HTML directory.
+HTML_IMAGES =
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files =
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+GTKDOC_CFLAGS = -I$(top_srcdir)/tests/fail/src $(TEST_DEPS_CFLAGS)
+GTKDOC_LIBS = $(TEST_DEPS_LIBS) $(top_builddir)/tests/fail/src/libtester.la
+
+# include generic part
+include $(top_srcdir)/tests/gtk-doc.notmpl.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST +=
+
+DISTCLEANFILES = \
+	gtkdoc-scan.log \
+	gtkdoc-scangobj.log \
+	gtkdoc-mktmpl.log \
+	gtkdoc-mkdb.log \
+	gtkdoc-mkhtml.log \
+	gtkdoc-fixxref.log
+

Added: trunk/tests/fail/docs/tester-docs.xml
==============================================================================
--- (empty file)
+++ trunk/tests/fail/docs/tester-docs.xml	Fri Jan 23 12:09:35 2009
@@ -0,0 +1,31 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude";>
+  <bookinfo>
+    <title>tester Reference Manual</title>
+    <releaseinfo>
+      for tester [VERSION].
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="http://[SERVER]/tester/index.html";>http://[SERVER]/tester/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>Tests</title>
+    <xi:include href="xml/tester.xml"/>
+  </chapter>
+
+  <index id="api-index">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+</book>

Added: trunk/tests/fail/docs/tester-sections.txt
==============================================================================
--- (empty file)
+++ trunk/tests/fail/docs/tester-sections.txt	Fri Jan 23 12:09:35 2009
@@ -0,0 +1,8 @@
+<SECTION>
+<FILE>tester</FILE>
+<TITLE>GtkdocTester</TITLE>
+Bug568711
+<SUBSECTION Standard>
+<SUBSECTION Private>
+</SECTION>
+

Added: trunk/tests/fail/src/Makefile.am
==============================================================================
--- (empty file)
+++ trunk/tests/fail/src/Makefile.am	Fri Jan 23 12:09:35 2009
@@ -0,0 +1,13 @@
+## Process this file with automake to produce Makefile.in
+
+if BUILD_TESTS
+
+noinst_LTLIBRARIES = libtester.la
+
+libtester_la_SOURCES = tester.c tester.h
+#libtester_la_LIBADD = $(TEST_DEPS_LIBS)
+
+AM_CPPFLAGS = $(TEST_DEPS_CFLAGS)
+
+endif
+

Added: trunk/tests/fail/src/tester.c
==============================================================================
--- (empty file)
+++ trunk/tests/fail/src/tester.c	Fri Jan 23 12:09:35 2009
@@ -0,0 +1,10 @@
+/**
+ * SECTION:tester
+ * @short_description: module for gtk-doc unit test
+ */
+
+#include <glib.h>
+
+#include "tester.h"
+
+

Added: trunk/tests/fail/src/tester.h
==============================================================================
--- (empty file)
+++ trunk/tests/fail/src/tester.h	Fri Jan 23 12:09:35 2009
@@ -0,0 +1,19 @@
+#ifndef GTKDOC_TESTER_H
+#define GTKDOC_TESTER_H
+
+#include <glib.h>
+
+/**
+ * Bug568711:
+ *
+ * Here we document the enum but not the values.
+ **/
+typedef enum {
+    BUG_568711_ENUM_1,
+    BUG_568711_ENUM_2,
+} Bug568711;
+
+
+
+#endif // GTKDOC_TESTER_H
+
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]