Merge pull request #2482 from bgrant0607/doctest

Add API documentation pre-commit hook.

.travis.yml

@@ -9,6 +9,7 @@ install:
   - ./hack/travis/install-etcd.sh
   - ./hack/verify-gofmt.sh
   - ./hack/verify-boilerplate.sh
+  - ./hack/verify-description.sh
   - ./hack/travis/install-std-race.sh
   - ./hack/build-go.sh
   - go get ./contrib/podex

hack/verify-description.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+
+# Copyright 2014 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+KUBE_ROOT=$(dirname "${BASH_SOURCE}")/..
+
+cd "${KUBE_ROOT}"
+
+result=0
+
+find_files() {
+  find . -not \( \
+      \( \
+        -wholename './output' \
+        -o -wholename './_output' \
+        -o -wholename './release' \
+        -o -wholename './target' \
+        -o -wholename '*/third_party/*' \
+        -o -wholename '*/Godeps/*' \
+      \) -prune \
+    \) -name '*.go'
+}
+
+find_files | egrep "pkg/api/v.[^/]*/types\.go" | grep -v v1beta3 | while read file ; do
+    if [[ "$("${KUBE_ROOT}/hooks/description.sh" "${file}")" -eq "0" ]]; then
+      echo "API file is missing the required field descriptions: ${file}"
+      result=1
+    fi
+done
+
+exit ${result}

hooks/description.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+# Copyright 2014 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Print 1 if the file in $1 is not in need of additional field descriptions, 0 otherwise.
+FILE="$1"
+
+if grep json: "${FILE}" | grep -v ,inline | grep -v -q description: ; then
+  echo "0"
+else
+  echo "1"
+fi
+exit 0
+

hooks/prepare-commit-msg

@@ -2,37 +2,48 @@
 
 KUBE_HOOKS_DIR="$(dirname "$(test -L "$0" && echo "$(dirname $0)/$(readlink "$0")" || echo "$0")")"
 
-files_need_gofmt=""
-files_need_boilerplate=""
+files_need_gofmt=()
+files_need_boilerplate=()
+files_need_description=()
 for file in $(git diff --cached --name-only --diff-filter ACM | grep "\.go" | grep -v -e "third_party" -e "Godeps"); do
   # Check for files that fail gofmt.
   diff="$(git show ":${file}" | gofmt -s -d)"
   if [[ -n "$diff" ]]; then
-    files_need_gofmt="${files_need_gofmt} ${file}"
+    files_need_gofmt+=("${file}")
   fi
 
   # Check for files without the required boilerplate.
-  boilerplate="$(${KUBE_HOOKS_DIR}/boilerplate.sh ${file})"
+  boilerplate=$("${KUBE_HOOKS_DIR}/boilerplate.sh" "${file}")
   if [[ "$boilerplate" -eq "0" ]]; then
-    files_need_boilerplate="${files_need_boilerplate} ${file}"
+    files_need_boilerplate+=("${file}")
   fi
 done
 
 # Check sh files for boilerplate
 for file in $(git diff --cached --name-only --diff-filter ACM | grep "\.sh" | grep -v "third_party"); do
   # Check for files without the required boilerplate.
-  boilerplate="$(${KUBE_HOOKS_DIR}/boilerplate.sh ${file})"
+  boilerplate=$("${KUBE_HOOKS_DIR}/boilerplate.sh" "${file}")
   if [[ "$boilerplate" -eq "0" ]]; then
-    files_need_boilerplate="${files_need_boilerplate} ${file}"
+    files_need_boilerplate+=("${file}")
   fi
 done
 
-if [[ -n "${files_need_gofmt}" ]]; then
+# Check API schema definitions for field descriptions
+# TODO: Check v1beta3, once it is documented
+for file in $(git diff --cached --name-only --diff-filter ACM | egrep "pkg/api/v.[^/]*/types\.go" | grep -v "third_party" | grep -v v1beta3); do
+  # Check for files with fields without description tags
+  descriptionless=$("${KUBE_HOOKS_DIR}/description.sh" "${file}")
+  if [[ "$descriptionless" -eq "0" ]]; then
+    files_need_description+=("${file}")
+  fi
+done
+
+if [[ "${#files_need_gofmt[@]}" -ne 0 ]]; then
   (
     echo
     echo "# *** ERROR: *** Some files have not been gofmt'd.  To fix these"
     echo "# errors, run gofmt -s -w <file>, or cut and paste the following:"
-    echo "#   gofmt -s -w ${files_need_gofmt}"
+    echo "#   gofmt -s -w ${files_need_gofmt[@]}"
     echo "#"
     echo "# Your commit will be aborted unless you override this warning. To"
     echo "# commit in spite of these format errors, delete the following line:"
@@ -40,12 +51,12 @@ if [[ -n "${files_need_gofmt}" ]]; then
   ) >> $1
 fi
 
-if [[ -n "${files_need_boilerplate}" ]]; then
+if [[ "${#files_need_boilerplate[@]}" -ne 0 ]]; then
   (
     echo
     echo "# *** ERROR: *** Some files are missing the required boilerplate"
     echo "# header from hooks/boilerplate.txt:"
-    for file in ${files_need_boilerplate}; do
+    for file in "${files_need_boilerplate[@]}"; do
       echo "#   ${file}"
     done
     echo "#"
@@ -54,3 +65,18 @@ if [[ -n "${files_need_boilerplate}" ]]; then
     echo
   ) >> $1
 fi
+
+if [[ "${#files_need_description[@]}" -ne 0 ]]; then
+  (
+    echo
+    echo "# *** ERROR: *** Some API files are missing the required field descriptions"
+    echo "# Add description tags to all non-inline fields in the following files:"
+    for file in "${files_need_description[@]}"; do
+      echo "#   ${file}"
+    done
+    echo "#"
+    echo "# Your commit will be aborted unless you fix these."
+    echo "#   COMMIT_BLOCKED_ON_DESCRIPTION"
+    echo
+  ) >> $1
+fi