From eea8abd59e070675d6c3560cda3f4a0c13db97ac Mon Sep 17 00:00:00 2001
From: Ankush Agarwal <ankushagarwal11@gmail.com>
Date: Tue, 31 Mar 2015 01:03:31 -0700
Subject: [PATCH] Add some documentation to pkg/system

Partially addresses #11581

Signed-off-by: Ankush Agarwal <ankushagarwal11@gmail.com>
---
 system/lstat.go              | 4 ++++
 system/lstat_test.go         | 1 +
 system/meminfo_linux.go      | 8 ++++++--
 system/meminfo_linux_test.go | 1 +
 system/mknod.go              | 2 ++
 system/stat.go               | 2 ++
 system/stat_linux.go         | 5 +++++
 system/stat_test.go          | 1 +
 system/stat_unsupported.go   | 1 +
 system/utimes_test.go        | 1 +
 10 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/system/lstat.go b/system/lstat.go
index 6c1ed2e..a966cd4 100644
--- a/system/lstat.go
+++ b/system/lstat.go
@@ -6,6 +6,10 @@ import (
 	"syscall"
 )
 
+// Lstat takes a path to a file and returns
+// a system.Stat_t type pertaining to that file.
+//
+// Throws an error if the file does not exist
 func Lstat(path string) (*Stat_t, error) {
 	s := &syscall.Stat_t{}
 	err := syscall.Lstat(path, s)
diff --git a/system/lstat_test.go b/system/lstat_test.go
index 9bab4d7..6bac492 100644
--- a/system/lstat_test.go
+++ b/system/lstat_test.go
@@ -5,6 +5,7 @@ import (
 	"testing"
 )
 
+// TestLstat tests Lstat for existing and non existing files
 func TestLstat(t *testing.T) {
 	file, invalid, _, dir := prepareFiles(t)
 	defer os.RemoveAll(dir)
diff --git a/system/meminfo_linux.go b/system/meminfo_linux.go
index b7de3ff..e2ca140 100644
--- a/system/meminfo_linux.go
+++ b/system/meminfo_linux.go
@@ -15,8 +15,8 @@ var (
 	ErrMalformed = errors.New("malformed file")
 )
 
-// Retrieve memory statistics of the host system and parse them into a MemInfo
-// type.
+// ReadMemInfo retrieves memory statistics of the host system and returns a
+//  MemInfo type.
 func ReadMemInfo() (*MemInfo, error) {
 	file, err := os.Open("/proc/meminfo")
 	if err != nil {
@@ -26,6 +26,10 @@ func ReadMemInfo() (*MemInfo, error) {
 	return parseMemInfo(file)
 }
 
+// parseMemInfo parses the /proc/meminfo file into
+// a MemInfo object given a io.Reader to the file.
+//
+// Throws error if there are problems reading from the file
 func parseMemInfo(reader io.Reader) (*MemInfo, error) {
 	meminfo := &MemInfo{}
 	scanner := bufio.NewScanner(reader)
diff --git a/system/meminfo_linux_test.go b/system/meminfo_linux_test.go
index 377405e..10ddf79 100644
--- a/system/meminfo_linux_test.go
+++ b/system/meminfo_linux_test.go
@@ -7,6 +7,7 @@ import (
 	"github.com/docker/docker/pkg/units"
 )
 
+// TestMemInfo tests parseMemInfo with a static meminfo string
 func TestMemInfo(t *testing.T) {
 	const input = `
 	MemTotal:      1 kB
diff --git a/system/mknod.go b/system/mknod.go
index 06f9c6a..26617eb 100644
--- a/system/mknod.go
+++ b/system/mknod.go
@@ -6,6 +6,8 @@ import (
 	"syscall"
 )
 
+// Mknod creates a filesystem node (file, device special file or named pipe) named path
+// with attributes specified by mode and dev
 func Mknod(path string, mode uint32, dev int) error {
 	return syscall.Mknod(path, mode, dev)
 }
diff --git a/system/stat.go b/system/stat.go
index 186e852..ba22b4d 100644
--- a/system/stat.go
+++ b/system/stat.go
@@ -4,6 +4,8 @@ import (
 	"syscall"
 )
 
+// Stat_t type contains status of a file. It contains metadata
+// like permission, owner, group, size, etc about a file
 type Stat_t struct {
 	mode uint32
 	uid  uint32
diff --git a/system/stat_linux.go b/system/stat_linux.go
index 072728d..928ba89 100644
--- a/system/stat_linux.go
+++ b/system/stat_linux.go
@@ -4,6 +4,7 @@ import (
 	"syscall"
 )
 
+// fromStatT converts a syscall.Stat_t type to a system.Stat_t type
 func fromStatT(s *syscall.Stat_t) (*Stat_t, error) {
 	return &Stat_t{size: s.Size,
 		mode: s.Mode,
@@ -13,6 +14,10 @@ func fromStatT(s *syscall.Stat_t) (*Stat_t, error) {
 		mtim: s.Mtim}, nil
 }
 
+// Stat takes a path to a file and returns
+// a system.Stat_t type pertaining to that file.
+//
+// Throws an error if the file does not exist
 func Stat(path string) (*Stat_t, error) {
 	s := &syscall.Stat_t{}
 	err := syscall.Stat(path, s)
diff --git a/system/stat_test.go b/system/stat_test.go
index abcc8ea..4534129 100644
--- a/system/stat_test.go
+++ b/system/stat_test.go
@@ -6,6 +6,7 @@ import (
 	"testing"
 )
 
+// TestFromStatT tests fromStatT for a tempfile
 func TestFromStatT(t *testing.T) {
 	file, _, _, dir := prepareFiles(t)
 	defer os.RemoveAll(dir)
diff --git a/system/stat_unsupported.go b/system/stat_unsupported.go
index 66323ee..7e0d034 100644
--- a/system/stat_unsupported.go
+++ b/system/stat_unsupported.go
@@ -6,6 +6,7 @@ import (
 	"syscall"
 )
 
+// fromStatT creates a system.Stat_t type from a syscall.Stat_t type
 func fromStatT(s *syscall.Stat_t) (*Stat_t, error) {
 	return &Stat_t{size: s.Size,
 		mode: uint32(s.Mode),
diff --git a/system/utimes_test.go b/system/utimes_test.go
index 1dea47c..350cce1 100644
--- a/system/utimes_test.go
+++ b/system/utimes_test.go
@@ -8,6 +8,7 @@ import (
 	"testing"
 )
 
+// prepareFiles creates files for testing in the temp directory
 func prepareFiles(t *testing.T) (string, string, string, string) {
 	dir, err := ioutil.TempDir("", "docker-system-test")
 	if err != nil {