Update READMEs

Top-level README spells out the need for low-deps and testing.

Moved per-package details to per-package READMEs.

Author: thockin

README.md

@@ -2,57 +2,37 @@
 
 [![Build Status]](https://travis-ci.org/kubernetes/utils) [![GoDoc](https://godoc.org/k8s.io/utils?status.svg)](https://godoc.org/k8s.io/utils)
 
-A set of Go libraries that provide low-level,
-kubernetes-independent packages supplementing the [Go
-standard libs].
+A set of Go libraries that provide low-level, kubernetes-independent packages
+supplementing the [Go standard libs].
 
 ## Purpose
 
-As Kubernetes grows and spins functionality out of its
-[core] and into cooperating repositories like
-[apiserver], [kubectl], [kubeadm], etc., the need
-arises for leaf repositories to house shared code and
-avoid cycles in repository relationships.
-
-This repository is intended to hold shared utilities
-with no Kubernetes dependence that may be of interest
-to any Go project.  See these [instructions for moving]
-an existing package to this repository.
+As Kubernetes grows and spins functionality out of its [core] and into
+cooperating repositories like [apiserver], [kubectl], [kubeadm], etc., the need
+arises for leaf repositories to house shared code and avoid cycles in repository
+relationships.
 
+This repository is intended to hold shared utilities with _no Kubernetes
+dependencies_ that may be of interest to any Go project.  See these [instructions
+for moving] an existing package to this repository.
 
 ## Criteria for adding code here
 
 - Used by multiple Kubernetes repositories.
 
-- Full unit test coverage.
-
-- Go tools compliant (`go get`, `go test`, etc.).
-
-- Complex enough to be worth vendoring, rather than copying.
+- Complex enough to be worth vendoring, rather than copying (e.g. not 5 LOC).
 
-- Stable, or backward compatible, API.
+- Can be fully exercised by unit tests (e.g. no dependencies on kernels).
 
-- _No dependence on any Kubernetes repository_.
+- Has full unit test coverage.
 
-## Libraries
+- Stable, or backward compatible, API, with complete godocs.
 
-- [Exec](/exec) provides an interface for `os/exec`. It makes it easier
-  to mock and replace in tests, especially with
-  the [FakeExec](exec/testing/fake_exec.go) struct.
-
-- [Temp](/temp) provides an interface to create temporary directories. It also
-  provides a [FakeDir](temp/temptest) implementation to replace in tests.
-
-- [Clock](/clock) provides an interface for time-based operations.  It allows
-  mocking time for testing.
-  
-- [Pointer](/pointer) provides some functions for pointer-based operations.
+- Go tools compliant (`go get`, `go test`, etc.).
 
-- [Io](/io) provides interfaces for working with file IO. Currently it provides
-  functionality for consistently reading a file.
+- Very few (ideally zero) external dependencies.
 
-- [NSEnter](/nsenter) provides interfaces for executing and interacting with
-  processes running within a namespace.
+- _No dependencies on any other Kubernetes repository_.
 
 [Build Status]: https://travis-ci.org/kubernetes/utils.svg?branch=master
 [Go standard libs]: https://golang.org/pkg/#stdlib

clock/README.md

@@ -0,0 +1,4 @@
+# Clock
+
+This package provides an interface for time-based operations.  It allows
+mocking time for testing.

exec/README.md

@@ -0,0 +1,5 @@
+# Exec
+
+This package provides an interface for `os/exec`. It makes it easier to mock
+and replace in tests, especially with the [FakeExec](testing/fake_exec.go)
+struct.

io/README.md

@@ -0,0 +1,4 @@
+# IO
+
+This package provides interfaces for working with file IO. Currently it
+provides functionality for consistently reading a file.

nsenter/README.md

@@ -0,0 +1,4 @@
+# NSEnter
+
+This package provides interfaces for executing and interacting with processes
+running within a namespace.

pointer/README.md

@@ -0,0 +1,3 @@
+# Pointer
+
+This package provides some functions for pointer-based operations.

temp/README.md

@@ -0,0 +1,4 @@
+# Temp
+
+This package provides an interface to create temporary directories. It also
+provides a [FakeDir](temp/temptest) implementation to replace in tests.