Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

executable file 88 lines (69 sloc) 2.109 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
#!/bin/bash
# Simple sanity checking of documentation of exceptions.
# Usage: go to src/ and run ../check_raise

header() {
  info=$1
  shift
result=$(mktemp)
  $* >$result
  cw=$(wc -w $result | cut -f1 -d\ )
  if [ "$cw" -ne "0" ]
  then
    echo $info
    cat $result
    echo
fi
}

setminus() {
  diff --new-line-format= --unchanged-line-format= $1 $2
}

# Capitalized Raise should be rare
header "Interesting places:" \
  grep -n Raise *

#header "Needs source style:" \
# grep -n "Invalid_argument[[:space:]]\"" *.mli

# Modules known to have documentation of exceptions OK
already_ok=$(mktemp)
echo "
batteriesHelp
batStack
batSplay
batReturn
batRef
batRandom
batQueue
batDeque
batConcurrent
batCharParser
" | sort >$already_ok

use_raise=$(mktemp)
doc_raise=$(mktemp)
poor_doc_raise=$(mktemp)
to_be_verified=$(mktemp)

# Crude check for presence of exceptions in implementations and interfaces
grep -n "\(raise\|invalid_arg\|failwith\)" *.ml | cut -f1 -d. | uniq | sort >$use_raise
grep -n @raise *.mli | cut -f1 -d. | uniq | sort >$doc_raise
grep -ni raise *.mli | cut -f1 -d. | uniq | sort >$poor_doc_raise

setminus $use_raise $already_ok >$to_be_verified

suspicious=$(mktemp)
setminus $to_be_verified $doc_raise >$suspicious

need_doc=$(mktemp)
setminus $suspicious $poor_doc_raise >$need_doc

header "Documentation of the following modules mentions exceptions and awaits formal @raise clauses:" \
  setminus $suspicious $need_doc

header "The following modules need raised exceptions to be documented (quite likely):" \
  cat $need_doc

# A policy: don't expose string arguments of standard exceptions
header "String arguments nobody should rely upon:" \
  grep -n "Invalid_argument[[:space:]]\"" *.mli

header "String arguments nobody should rely upon:" \
  grep -n "Failure[[:space:]]\"" *.mli

# Look for mistakes

header "@raises instead of @raise:" \
  grep -n @raises *

header "Square brackets that harm ocamldoc:" \
  grep -n "@raise[[:space:]]\[" *

header Typos: \
  grep -n "Invalid_arg[[:space:]]" `find . -not -name batDynArray\*`

header Typos: \
  grep -n Invald_argument *
Something went wrong with that request. Please try again.