Remove hi_ prefixes from internal code. Add documentation.

src/filewatcher/filewatcher.h

@@ -21,8 +21,9 @@
  * memory inside the file watcher struct.
  */
 typedef struct {
-  const char *pathname; // Pathname given to a `hi_file_watcher_add` call.
-                        // Do not free.
+  /** Path of the file this event is about. Do not free. */
+  const char *pathname;
+  /** Might not be only those given to @a file_watcher_add. */
   FileWatchType type;
 } FileEvent;
 
@@ -31,44 +32,38 @@ typedef struct FileWatcher FileWatcher;
 /**
  * FileEvents is a thread safe list of events.
  *
- * It is implemented as a stack, so the events will be popped
- * in reverse chronological order.
- * */
+ * Events will be popped mostly in reverse chronological order, but strict
+ * chronology is not guaranteed.
+ */
 typedef struct FileEvents FileEvents;
 
 /**
  * Create watcher and necessary data to run it.
  *
- * Will start the watcher thread immediately.
+ * Starts a new watcher thread immediately.
  */
-FileWatcher *hi_file_watcher_create(void);
+FileWatcher *file_watcher_create(void);
 
 /**
- * Destroy a previously created file watcher context.
+ * Destroy a previously created file watcher.
  *
- * Will join the thread and destroy event stack.
+ * Will join the thread and destroy event stack. Any FileEvent still in
+ * existence will contain invalid data after this call.
  */
-void hi_file_watcher_destroy(FileWatcher *context);
+void file_watcher_destroy(FileWatcher *fw);
 
 /**
- * Add a file to the watch list of a file watcher.
+ * Start watching for events on a file.
  *
- * @param context Previously created watcher context
+ * @param fw The watcher instance
  * @param pathname Absolute path to the file or directory
- * @param flags The events that will be watched for
+ * @param flags The event mask for the events to watch for
  */
-HiResult hi_file_watcher_add(FileWatcher *context,
-                                 const char *pathname, u32 flags);
-/**
- * Can be used to poke file watcher thread to make sure it empties
- * events before doing something, e.g. for shutting it down.
- */
-void hi_file_watcher_notify(FileWatcher *context);
+HiResult file_watcher_add(FileWatcher *fw, const char *pathname, u32 flags);
 
 /**
- * Pop an event from event stack. Call `hi_file_event_destroy` when done with
- * it.
+ * Pop an event from event stack.
  */
-FileEvent hi_file_event_pop(FileWatcher *ctx);
+FileEvent file_event_pop(FileWatcher *ctx);
 
 #endif // HI_FILEWATCHER_H_