Add some documentation to pkg/system

Partially addresses #11581

Signed-off-by: Ankush Agarwal <ankushagarwal11@gmail.com>

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)

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)

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)

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

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)
 }

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

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)

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)

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),

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 {