From 5d29d4c39d1c082535410510be6c54e349e1e3a7 Mon Sep 17 00:00:00 2001
From: Luke Shumaker <lukeshu@sbcglobal.net>
Date: Fri, 18 Sep 2015 17:45:34 -0400
Subject: Massive documentation and copyright clean-up.

---
 inotify/inotify.go | 47 ++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 42 insertions(+), 5 deletions(-)

(limited to 'inotify/inotify.go')

diff --git a/inotify/inotify.go b/inotify/inotify.go
index 0d67b44..2fd3a83 100644
--- a/inotify/inotify.go
+++ b/inotify/inotify.go
@@ -1,3 +1,21 @@
+// Copyright 2015 Luke Shumaker <lukeshu@sbcglobal.net>.
+//
+// This is free software; you can redistribute it and/or modify it
+// under the terms of the GNU Lesser General Public License as
+// published by the Free Software Foundation; either version 2.1 of the
+// License, or (at your option) any later version.
+//
+// This software is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public
+// License along with this manual; if not, see
+// <http://www.gnu.org/licenses/>.
+
+// Package inotify provides an interface to the Linux inotify system.
+// The inotify system is a mechanism for monitoring filesystem events.
 package inotify
 
 import (
@@ -7,7 +25,7 @@ import (
 )
 
 type Inotify struct {
-	fd       Fd
+	fd       file
 	fdLock   sync.RWMutex
 	buffFull [4096]byte
 	buff     []byte
@@ -15,12 +33,14 @@ type Inotify struct {
 }
 
 type Event struct {
-	Wd     Wd      /* Watch descriptor */
-	Mask   Mask    /* Mask describing event */
-	Cookie uint32  /* Unique cookie associating related events (for rename(2)) */
-	Name   *string /* Optional name */
+	Wd     Wd      // Watch descriptor
+	Mask   Mask    // Mask describing event
+	Cookie uint32  // Unique cookie associating related events (for rename(2))
+	Name   *string // Optional name
 }
 
+// Create an inotify instance.  The variant InotifyInit1() allows
+// flags to access extra functionality.
 func InotifyInit() (*Inotify, error) {
 	fd, err := inotify_init()
 	o := Inotify{
@@ -30,6 +50,8 @@ func InotifyInit() (*Inotify, error) {
 	return &o, err
 }
 
+// Create an inotify instance, with flags specifying extra
+// functionality.
 func InotifyInit1(flags int) (*Inotify, error) {
 	fd, err := inotify_init1(flags)
 	o := Inotify{
@@ -39,18 +61,29 @@ func InotifyInit1(flags int) (*Inotify, error) {
 	return &o, err
 }
 
+// Add a watch to the inotify instance, or modifies an existing watch
+// item.
 func (o *Inotify) AddWatch(path string, mask Mask) (Wd, error) {
 	o.fdLock.RLock()
 	defer o.fdLock.RUnlock()
 	return inotify_add_watch(o.fd, path, mask)
 }
 
+// Remove a watch from the inotify instance.
 func (o *Inotify) RmWatch(wd Wd) error {
 	o.fdLock.RLock()
 	defer o.fdLock.RUnlock()
 	return inotify_rm_watch(o.fd, wd)
 }
 
+// Close the inotify instance; further calls to this object will
+// error.
+//
+// Events recieved before Close() is called may still be Read() after
+// the call to Close().
+//
+// Beware that if Close() is called while waiting on Read(), it will
+// block until events are read.
 func (o *Inotify) Close() error {
 	o.fdLock.Lock()
 	defer o.fdLock.Unlock()
@@ -58,6 +91,10 @@ func (o *Inotify) Close() error {
 	return sysclose(o.fd)
 }
 
+// Read an event from the inotify instance.
+//
+// Events recieved before Close() is called may still be Read() after
+// the call to Close().
 func (o *Inotify) Read() (Event, error) {
 	o.buffLock.Lock()
 	defer o.buffLock.Unlock()
-- 
cgit v1.2.3