doc: Add script to enforce stricter validation of documentation comments

src/Makefile.am

@@ -89,7 +89,7 @@ TESTS_ENVIRONMENT = \
 	$(NULL)
 TESTS_SH = \
 	check-def.sh \
-	check-doc-syntax.sh\
+	check-doc-syntax.sh \
 	check-headers.sh \
 	check-plt.sh \
 	check-preprocessor-syntax.sh \
@@ -100,7 +100,7 @@ else
 TESTS += check-link$(EXEEXT)
 endif
 
-EXTRA_DIST += $(TESTS_SH) check-has-hidden-symbols.c
+EXTRA_DIST += $(TESTS_SH) check-has-hidden-symbols.c check-doc-syntax.awk
 check_PROGRAMS += check-link
 check_link_LDADD = libcairo.la
 

src/check-doc-syntax.awk

@@ -0,0 +1,105 @@
+#!/usr/bin/awk -f
+
+BEGIN {
+    name_found = 1
+    SECTION_DOC = 0
+    PUBLIC_DOC = 1
+    PRIVATE_DOC = 2
+}
+
+function log_msg(severity, msg)
+{
+    printf "%s (%d): %s: %s %s\n", FILENAME, FNR, severity, doc_name, msg
+}
+
+function log_error(msg)
+{
+    log_msg("ERROR", msg)
+}
+
+function log_warning(msg)
+{
+    log_msg("WARNING", msg)
+}
+
+/^\/\*\*$/ {
+    in_doc = 1
+    doc_line = 0
+}
+
+/^(\/\*\*$| \*[ \t]| \*$| \*\*\/$)/ {
+    valid_doc = 1
+}
+
+in_doc {
+    if (!valid_doc)
+	log_error("bad line: '" $0 "'")
+    valid_doc = 0
+
+    doc_line++
+    if (doc_line == 2) {
+	# new doc name. Did we find the previous one?
+	# (macros are not expected to be found in the same place as
+	# their documentation)
+	if (!name_found && doc_name !~ /CAIRO_/)
+	    log_warning("not found")
+	doc_name = $2
+	if (doc_name ~ /^SECTION:.*$/) {
+	    doc_type = SECTION_DOC
+	    name_found = 1
+	} else if (tolower(doc_name) ~ /^cairo_[a-z0-9_]*:$/) {
+	    doc_type = PUBLIC_DOC
+	    name_found = 0
+	    real_name = substr(doc_name, 1, length(doc_name) - 1)
+	} else if (tolower(doc_name) ~ /^_[a-z0-9_]*:$/) {
+	    doc_type = PRIVATE_DOC
+	    name_found = 0
+	    real_name = substr(doc_name, 1, length(doc_name) - 1)
+	} else {
+	    log_error("invalid doc id (should be 'cairo_...:')")
+	    name_found = 1
+	}
+    }
+}
+
+!in_doc {
+    regex = "(^|[ \\t\\*])" real_name "([ ;()]|$)"
+    if ($0 ~ regex)
+	name_found = 1
+}
+
+/^ \* Since: ([0-9]*.[0-9]*|TBD)$/ {
+    doc_has_since = doc_line
+}
+
+/^ \*\*\// {
+    if (doc_type == PUBLIC_DOC) {
+	if (!doc_has_since) {
+	    # private types can start with cairo_
+	    if (doc_name ~ /^cairo_.*_t:$/)
+		log_warning("missing 'Since' field (is it a private type?)")
+	    else
+		log_error("missing 'Since' field")
+	} else if (doc_has_since != doc_line - 1)
+	    log_warning("misplaced 'Since' field (should be right before the end of the comment)")
+    } else {
+	if (doc_has_since)
+	    log_warning("'Since' field in non-public element")
+    }
+
+    in_doc = 0
+    doc_has_since = 0
+    doc_type = 0
+}
+
+/\*\// {
+    if (in_doc) {
+	in_doc = 0
+ 	log_error("documentation comment not closed with **/")
+    }
+}
+
+END {
+    if (!name_found)
+	log_warning("not found")
+}

src/check-doc-syntax.sh

@@ -70,4 +70,8 @@ if echo $FILES | xargs grep "$note_regexp" /dev/null; then
 	echo Be civil and replace it by 'Note' please.
 fi >&2
 
+if echo $FILES | xargs ./check-doc-syntax.awk ; then
+	stat=1
+fi >&2
+
 exit $stat