Standardised documentation

author: Camil Staps 2017-06-09 09:37:47 +0000
committer: Camil Staps 2017-06-09 09:43:36 +0000
commit: a3202102784845bda49607b7022a92af5ece6095 (patch)
tree: 6fa4f6f052f90907feea113ad7f69203b53e0c89
parent: Readme; 80 chars (diff)
2 files changed, 193 insertions, 53 deletions
diff --git a/Inotify.dcl b/Inotify.dcl
index 82c83c1..0fa983d 100644
--- a/Inotify.dcl
+++ b/Inotify.dcl
@@ -1,61 +1,89 @@
 definition module Inotify
 
+/**
+ * Links with Linux's inotify
+ */
+
 from Data.Either import ::Either
 from Data.Maybe import ::Maybe
 
-// Inotify file descriptor
+/**
+ * An inotify file descriptor
+ *
+ * @var A state that is used for callbacks
+ */
 :: *Inotify st
-// Inotify watch descriptor
+
+/**
+ * An inotify watch descriptor
+ */
 :: INWatch
 
-// Inotify event mask
+/**
+ * An inotify event mask
+ */
 :: INMask :== Int
 
-// Inotify event
+/**
+ * An inotify event
+ */
 :: INEvent :== Int
 
-// Inotify callback: event, maybe filename, state, world -> state, world
+/**
+ * An inotify callback: event, maybe filename, state, world -> state, world
+ *
+ * @var A state that is passed on.
+ */
 :: INCallback st :== INEvent (Maybe String) st *World -> *(st, *World)
 
+/**
+ * Bitwise OR for event masks
+ */
 (|-) infixl 6 :: (INMask INMask -> INMask)
 
-/* Initialise an inotify file descriptor with some state */
+/**
+ * Initialise an inotify file descriptor with some state.
+ *
+ * @param The initial state
+ * @result A file descriptor or Nothing if the C initialisation failed
+ */
 inotify_init :: st -> Maybe *(Inotify st)
 
-/* Close an inotify file descriptor and get back the state */
+/**
+ * Close an inotify file descriptor and get back the state
+ *
+ * @param The file descriptor
+ * @result The final state
+ */
 inotify_close :: *(Inotify st) -> st
 
 /**
  * Add a watch on some file
  *
- * INCallback st: the callback for events
- * INMask:        a mask of events to watch for
- * String:        the filename
- * Inotify st:    the inotify file descriptor
- *
- * Either Int INWatch: either an error code or a watch descriptor
- * Inotify st:    the new file descriptor
+ * @param The callback for events
+ * @param A mask of events to watch for
+ * @param The filename
+ * @param The inotify file descriptor
+ * @result Either an error code or a watch descriptor, and the inotify file descriptor
  */
 inotify_add_watch :: (INCallback st) !INMask !String !*(Inotify st)
-                  -> *(!Either Int INWatch, !*Inotify st)
+	-> *(!Either Int INWatch, !*Inotify st)
 
 /**
  * Remove a watch
  *
- * INWatch:       the watch to remove
- * Inotify st:    the inotify file descriptor
- *
- * Bool:          success
- * Inotify st:    the new file descriptor
+ * @param The watch to remove
+ * @param The inotify file descriptor
+ * @result A boolean indicating success and the inotify file descriptor
  */
 inotify_rm_watch :: !INWatch !*(Inotify st) -> *(!Bool, !*Inotify st)
 
 /**
  * Poll an inotify file descriptor; i.e. wait for new events
  *
- * Maybe Int      timeout in milliseconds (Nothing for no timeout)
- *
- * Int            the number of events
+ * @param Timeout in milliseconds (Nothing for no timeout)
+ * @param The inotify file descriptor
+ * @result The number of events, and the inotify file descriptor
  */
 inotify_poll :: !(Maybe Int) !*(Inotify st) -> *(!Int, !*Inotify st)
 
@@ -66,46 +94,158 @@ inotify_check :: !*(Inotify st) !*World -> *(!*Inotify st, !*World)
 
 /**
  * Check if an event matches a mask
+ *
+ * @param The mask
+ * @param The event
+ * @result True iff the event matches the mask
  */
 inotify_is_event :: INMask INEvent -> Bool
 
 /**
  * Combination of inotify_poll and inotify_check that will return only if no
  * events were given when a timeout occurred.
+ *
+ * @param Timeout in milliseconds (Nothing for no timeout)
+ * @param The inotify file descriptor
+ * @param The World
+ * @result The inotify file descriptor and the World. However, the function
+ *   only returns if no events were given when the timeout occurred. Otherwise,
+ *   it will loop.
  */
 inotify_loop_with_timeout :: !(Maybe Int) !*(Inotify st) !*World
-                          -> *(!*Inotify st, !*World)
+	-> *(!*Inotify st, !*World)
 
 /**
  * inotify_loop_with_timeout with Nothing as timeout (will never return)
+ *
+ * @param The inotify file descriptor
+ * @param The World
+ * @result The parameters back, however, this function will never return.
  */
 inotify_loop_forever :: !*(Inotify st) !*World -> *(!*Inotify st, !*World)
 
 /*** Begin inotify.h ***/
 
-IN_ACCESS        :== 0x00000001 // File was accessed
-IN_MODIFY        :== 0x00000002 // File was modified
-IN_ATTRIB        :== 0x00000004 // Metadata changed
-IN_CLOSE_WRITE   :== 0x00000008 // Writtable file was closed
-IN_CLOSE_NOWRITE :== 0x00000010 // Unwrittable file closed
-IN_OPEN          :== 0x00000020 // File was opened
-IN_MOVED_FROM    :== 0x00000040 // File was moved from X
-IN_MOVED_TO      :== 0x00000080 // File was moved to Y
-IN_CREATE        :== 0x00000100 // Subfile was created
-IN_DELETE        :== 0x00000200 // Subfile was deleted
-IN_DELETE_SELF   :== 0x00000400 // Self was deleted
-IN_MOVE_SELF     :== 0x00000800 // Self was moved
-IN_UNMOUNT       :== 0x00002000 // Backing fs was unmounted
-IN_Q_OVERFLOW    :== 0x00004000 // Event queued overflowed
-IN_IGNORED       :== 0x00008000 // File was ignored
-IN_CLOSE         :== (IN_CLOSE_WRITE |- IN_CLOSE_NOWRITE) // close
-IN_MOVE          :== (IN_MOVED_FROM |- IN_MOVED_TO) // moves
-IN_ONLYDIR       :== 0x01000000 // only watch the path if it is a directory
-IN_DONT_FOLLOW   :== 0x02000000 // don't follow a sym link
-IN_EXCL_UNLINK   :== 0x04000000 // exclude events on unlinked objects
-IN_MASK_ADD      :== 0x20000000 // add to the mask of an already existing watch
-IN_ISDIR         :== 0x40000000 // event occurred against dir
-IN_ONESHOT       :== 0x80000000 // only send event once
+/**
+ * Inotify event mask: file was accessed
+ */
+IN_ACCESS        :== 0x00000001
+
+/**
+ * Inotify event mask: file was modified
+ */
+IN_MODIFY        :== 0x00000002
+
+/**
+ * Inotify event mask: metadata changed
+ */
+IN_ATTRIB        :== 0x00000004
+
+/**
+ * Inotify event mask: file opened for writing was closed
+ */
+IN_CLOSE_WRITE   :== 0x00000008
+
+/**
+ * Inotify event mask: file not opened for writing was closed
+ */
+IN_CLOSE_NOWRITE :== 0x00000010
+
+/**
+ * Inotify event mask: file was opened
+ */
+IN_OPEN          :== 0x00000020
+
+/**
+ * Inotify event mask: file was moved from watched directory
+ */
+IN_MOVED_FROM    :== 0x00000040
+
+/**
+ * Inotify event mask: file was moved to watched directory
+ */
+IN_MOVED_TO      :== 0x00000080
+
+/**
+ * Inotify event mask: file was created in watched directory
+ */
+IN_CREATE        :== 0x00000100
+
+/**
+ * Inotify event mask: file in watched directory was deleted
+ */
+IN_DELETE        :== 0x00000200
+
+/**
+ * Inotify event mask: watched file was deleted
+ */
+IN_DELETE_SELF   :== 0x00000400
+
+/**
+ * Inotify event mask: watched file was moved
+ */
+IN_MOVE_SELF     :== 0x00000800
+
+/**
+ * Inotify event mask: backing fs of watched file was unmounted
+ */
+IN_UNMOUNT       :== 0x00002000
+
+/**
+ * Inotify event mask: the inotify event queue overflowed
+ */
+IN_Q_OVERFLOW    :== 0x00004000
+
+/**
+ * Inotify event mask: the watch has been removed, either through
+ * inotify_rm_watch or because it was deleted, the fs was unmounted, etc.
+ */
+IN_IGNORED       :== 0x00008000
+
+/**
+ * Inotify event mask: watched file was closed
+ */
+IN_CLOSE         :== (IN_CLOSE_WRITE |- IN_CLOSE_NOWRITE)
+
+/**
+ * Inotify event mask: a file was moved from or to a watched directory
+ */
+IN_MOVE          :== (IN_MOVED_FROM |- IN_MOVED_TO)
+
+/**
+ * Inotify event mask: only watch the path if it is a directory
+ */
+IN_ONLYDIR       :== 0x01000000
+
+/**
+ * Inotify event mask: don't follow symlinks
+ */
+IN_DONT_FOLLOW   :== 0x02000000
+
+/**
+ * Inotify event mask: stop watching files when they get unlinked
+ */
+IN_EXCL_UNLINK   :== 0x04000000
+
+/**
+ * Inotify event mask: when adding a watch on a path for which a watch already
+ * exists, OR the new event mask with the old one instead of replacing it.
+ */
+IN_MASK_ADD      :== 0x20000000
+
+/**
+ * Inotify event mask: the event occurred against a directory
+ */
+IN_ISDIR         :== 0x40000000
+
+/**
+ * Inotify event mask: monitor a watch only for one event, then remove it
+ */
+IN_ONESHOT       :== 0x80000000
+
+/**
+ * Inotify event mask: OR of all events
+ */
 IN_ALL_EVENTS    :==
 	(IN_ACCESS |- IN_MODIFY |- IN_ATTRIB |- IN_CLOSE_WRITE |- IN_CLOSE_NOWRITE
 	|- IN_OPEN |- IN_MOVED_FROM |- IN_MOVED_TO |- IN_DELETE |- IN_CREATE |-
diff --git a/inotify_c.c b/inotify_c.c
index e63ebfb..0521b95 100644
--- a/inotify_c.c
+++ b/inotify_c.c
@@ -14,12 +14,12 @@
  * The result should be freed.
  */
 char* clstocs(CleanString* cs) {
-    char* s = calloc(CleanStringLength(cs) + 1, 1);
-    uint8_t i;
-    for (i = 0; i < CleanStringLength(cs); i++)
-        s[i] = CleanStringCharacters(cs)[i];
-    s[i] = 0;
-    return s;
+	char* s = calloc(CleanStringLength(cs) + 1, 1);
+	uint8_t i;
+	for (i = 0; i < CleanStringLength(cs); i++)
+		s[i] = CleanStringCharacters(cs)[i];
+	s[i] = 0;
+	return s;
 }
 
 /** The empty string, as a CleanString */
author	Camil Staps	2017-06-09 09:37:47 +0000
committer	Camil Staps	2017-06-09 09:43:36 +0000
commit	a3202102784845bda49607b7022a92af5ece6095 (patch)
tree	6fa4f6f052f90907feea113ad7f69203b53e0c89
parent	Readme; 80 chars (diff)