src/check-doc-syntax.awk

   1 #!/usr/bin/awk -f
   2
   3 BEGIN {
   4     name_found = 1
   5     SECTION_DOC = 0
   6     PUBLIC_DOC = 1
   7     PRIVATE_DOC = 2
   8 }
   9
  10 function log_msg(severity, msg)
  11 {
  12     printf "%s (%d): %s: %s %s\n", FILENAME, FNR, severity, doc_name, msg
  13 }
  14
  15 function log_error(msg)
  16 {
  17     log_msg("ERROR", msg)
  18 }
  19
  20 function log_warning(msg)
  21 {
  22     log_msg("WARNING", msg)
  23 }
  24
  25 /^\/\*\*$/ {
  26     in_doc = 1
  27     doc_line = 0
  28 }
  29
  30 /^(\/\*\*$| \*[ \t]| \*$| \*\*\/$)/ {
  31     valid_doc = 1
  32 }
  33
  34 in_doc {
  35     if (!valid_doc)
  36         log_error("bad line: '" $0 "'")
  37     valid_doc = 0
  38
  39     doc_line++
  40     if (doc_line == 2) {
  41         # new doc name. Did we find the previous one?
  42         # (macros are not expected to be found in the same place as
  43         # their documentation)
  44         if (!name_found && doc_name !~ /CAIRO_/)
  45             log_warning("not found")
  46         doc_name = $2
  47         if (doc_name ~ /^SECTION:.*$/) {
  48             doc_type = SECTION_DOC
  49             name_found = 1
  50         } else if (tolower(doc_name) ~ /^cairo_[a-z0-9_]*:$/) {
  51             doc_type = PUBLIC_DOC
  52             name_found = 0
  53             real_name = substr(doc_name, 1, length(doc_name) - 1)
  54         } else if (tolower(doc_name) ~ /^_[a-z0-9_]*:$/) {
  55             doc_type = PRIVATE_DOC
  56             name_found = 0
  57             real_name = substr(doc_name, 1, length(doc_name) - 1)
  58         } else {
  59             log_error("invalid doc id (should be 'cairo_...:')")
  60             name_found = 1
  61         }
  62     }
  63 }
  64
  65 !in_doc {
  66     regex = "(^|[ \\t\\*])" real_name "([ ;()]|$)"
  67     if ($0 ~ regex)
  68         name_found = 1
  69 }
  70
  71 /^ \* Since: ([0-9]*.[0-9]*|TBD)$/ {
  72     if (doc_has_since != 0) {
  73         log_error("Duplicate 'Since' field")
  74     }
  75     doc_has_since = doc_line
  76 }
  77
  78 /^ \*\*\// {
  79     if (doc_type == PUBLIC_DOC) {
  80         if (!doc_has_since) {
  81             # private types can start with cairo_
  82             if (doc_name ~ /^cairo_.*_t:$/)
  83                 log_warning("missing 'Since' field (is it a private type?)")
  84             else
  85                 log_error("missing 'Since' field")
  86         } else if (doc_has_since != doc_line - 1)
  87             log_warning("misplaced 'Since' field (should be right before the end of the comment)")
  88     } else {
  89         if (doc_has_since)
  90             log_warning("'Since' field in non-public element")
  91     }
  92
  93     in_doc = 0
  94     doc_has_since = 0
  95     doc_type = 0
  96 }
  97
  98 /\*\// {
  99     if (in_doc) {
 100         in_doc = 0
 101         log_error("documentation comment not closed with **/")
 102     }
 103 }
 104
 105 END {
 106     if (!name_found)
 107         log_warning("not found")
 108 }