Add examples for kubectl describe, and make gendocs less spammy

Makes hack/{run/verify}-gendocs.sh ignore generated-timestamp-only
changes so minor changes to kubectl don't have to touch the entire
set of md docs.

hack/lib/util.sh

@@ -119,17 +119,13 @@ kube::util::wait-for-jobs() {
   return ${fail}
 }
 
-# takes a binary to run $1 and then copies the results to $2
+# Takes a binary to run $1 and then copies the results to $2.
+# If the generated and original files are the same after filtering lines
+# that match $3, copy is skipped.
 kube::util::gen-doc() {
   local cmd="$1"
   local dest="$2"
-
-  # remove all old generated file from the destination
-  for file in $(cat "${dest}/.files_generated" 2>/dev/null); do
-    set +e
-    rm "${dest}/${file}"
-    set -e
-  done
+  local skipprefix="${3:-}"
 
   # We do this in a tmpdir in case the dest has other non-autogenned files
   # We don't want to include them in the list of gen'd files
@@ -139,6 +135,22 @@ kube::util::gen-doc() {
   ${cmd} "${tmpdir}"
   # create the list of generated files
   ls "${tmpdir}" | LC_ALL=C sort > "${tmpdir}/.files_generated"
+
+  # remove all old generated file from the destination
+  while read file; do
+    if [[ -e "${tmpdir}/${file}" && -n "${skipprefix}" ]]; then
+      local original generated
+      original=$(grep -v "^${skipprefix}" "${dest}/${file}") || :
+      generated=$(grep -v "^${skipprefix}" "${tmpdir}/${file}") || :
+      if [[ "${original}" == "${generated}" ]]; then
+        # overwrite generated with original.
+        mv "${dest}/${file}" "${tmpdir}/${file}"
+      fi
+    else
+      rm "${dest}/${file}" || true
+    fi
+  done <"${dest}/.files_generated"
+
   # put the new generated file into the destination
   find "${tmpdir}" -exec rsync -pt {} "${dest}" \; >/dev/null
   #cleanup