Add doxygen-style comments to functions from os/fs.c.

2 files changed, 59 insertions, 29 deletions

diff --git a/src/os/fs.c b/src/os/fs.c
index 8d3e8d1627..711262740e 100644
--- a/src/os/fs.c
+++ b/src/os/fs.c
@@ -16,8 +16,6 @@ int os_chdir(const char *path) {
   return uv_chdir(path);
 }
 
-// Get name of current directory into buffer 'buf' of length 'len' bytes.
-// Return OK for success, FAIL for failure.
 int os_dirname(char_u *buf, size_t len)
 {
   assert(buf && len);
@@ -30,10 +28,10 @@ int os_dirname(char_u *buf, size_t len)
   return OK;
 }
 
-// Get the absolute name of the given relative directory.
-//
-// parameter directory: Directory name, relative to current directory.
-// return FAIL for failure, OK for success
+/// Get the absolute name of the given relative directory.
+///
+/// @param directory Directory name, relative to current directory.
+/// @return `FAIL` for failure, `OK` for success.
 int os_full_dir_name(char *directory, char *buffer, int len)
 {
   int retval = OK;
@@ -110,12 +108,6 @@ int append_path(char *path, const char *to_append, int max_len)
   return OK;
 }
 
-// Get absolute file name into "buf[len]".
-//
-// parameter force: Also expand when the given path in fname is already
-// absolute.
-//
-// return FAIL for failure, OK for success
 int os_get_absolute_path(char_u *fname, char_u *buf, int len, int force)
 {
   char_u *p;
@@ -142,15 +134,11 @@ int os_get_absolute_path(char_u *fname, char_u *buf, int len, int force)
   return append_path((char *) buf, (char *) end_of_path, len);
 }
 
-// Return TRUE if "fname" does not depend on the current directory.
 int os_is_absolute_path(const char_u *fname)
 {
   return *fname == '/' || *fname == '~';
 }
 
-// return TRUE if "name" is a directory
-// return FALSE if "name" is not a directory
-// return FALSE for error
 int os_isdir(const char_u *name)
 {
   int32_t mode = os_getperm(name);
@@ -168,8 +156,6 @@ int os_isdir(const char_u *name)
 static int is_executable(const char_u *name);
 static int is_executable_in_path(const char_u *name);
 
-// Return TRUE if "name" is executable and can be found in $PATH, is absolute
-// or relative to current dir, FALSE if not.
 int os_can_exe(const char_u *name)
 {
   // If it's an absolute or relative path don't need to use $PATH.
@@ -199,8 +185,9 @@ static int is_executable(const char_u *name)
   return FALSE;
 }
 
-// Return TRUE if "name" can be found in $PATH and executed, FALSE if not or an
-// error occurs.
+/// Check if a file is inside the $PATH and is executable.
+///
+/// @return `TRUE` if `name` is an executable inside $PATH.
 static int is_executable_in_path(const char_u *name)
 {
   const char *path = getenv("PATH");
@@ -248,8 +235,6 @@ static int is_executable_in_path(const char_u *name)
   return FALSE;
 }
 
-// Get file permissions for 'name'.
-// Returns -1 when it doesn't exist.
 int32_t os_getperm(const char_u *name)
 {
   uv_fs_t request;
@@ -265,8 +250,6 @@ int32_t os_getperm(const char_u *name)
   }
 }
 
-// Set file permission for 'name' to 'perm'.
-// Returns FAIL for failure, OK otherwise.
 int os_setperm(const char_u *name, int perm)
 {
   uv_fs_t request;
@@ -281,7 +264,6 @@ int os_setperm(const char_u *name, int perm)
   }
 }
 
-// return TRUE if "name" exists.
 int os_file_exists(const char_u *name)
 {
   uv_fs_t request;
diff --git a/src/os/os.h b/src/os/os.h
index eb25735d6f..6a5bb156cd 100644
--- a/src/os/os.h
+++ b/src/os/os.h
@@ -3,13 +3,64 @@
 
 #include "vim.h"
 
-long_u os_total_mem(int special);
+/// Change to the given directory.
+///
+/// @return `0` on success, a libuv error code on failure.
 int os_chdir(const char *path);
+
+/// Get the name of current directory.
+///
+/// @param buf Buffer to store the directory name.
+/// @param len Length of `buf`.
+/// @return `OK` for success, `FAIL` for failure.
 int os_dirname(char_u *buf, size_t len);
+
+/// Expand a given file to its absolute path.
+///
+/// @param fname The filename which should be expanded.
+/// @param buf Buffer to store the absolute path of `fname`.
+/// @param len Length of `buf`.
+/// @param force Also expand when `fname` is already absolute.
+/// @return `FAIL` for failure, `OK` for success.
 int os_get_absolute_path(char_u *fname, char_u *buf, int len, int force);
+
+/// Check if the given file is absolute.
+///
+/// This just checks if the file name starts with '/' or '~'.
+/// @return `TRUE` if "fname" is absolute.
 int os_is_absolute_path(const char_u *fname);
+
+/// Check if the given path is a directory or not.
+///
+/// @return `TRUE` if `fname` is a directory.
 int os_isdir(const char_u *name);
+
+/// Check if the given path represents an executable file.
+///
+/// @return `TRUE` if `name` is executable and
+///   - can be found in $PATH,
+///   - is relative to current dir or
+///   - is absolute.
+///
+/// @return `FALSE` otherwise.
 int os_can_exe(const char_u *name);
+
+/// Get the file permissions for a given file.
+///
+/// @return `-1` when `name` doesn't exist.
+int32_t os_getperm(const char_u *name);
+
+/// Set the permission of a file.
+///
+/// @return `OK` for success, `FAIL` for failure.
+int os_setperm(const char_u *name, int perm);
+
+/// Check if a file exists.
+///
+/// @return `TRUE` if `name` exists.
+int os_file_exists(const char_u *name);
+
+long_u os_total_mem(int special);
 const char *os_getenv(const char *name);
 int os_setenv(const char *name, const char *value, int overwrite);
 char *os_getenvname_at_index(size_t index);
@@ -17,8 +68,5 @@ int os_get_usernames(garray_T *usernames);
 int os_get_user_name(char *s, size_t len);
 int os_get_uname(uid_t uid, char *s, size_t len);
 char *os_get_user_directory(const char *name);
-int32_t os_getperm(const char_u *name);
-int os_setperm(const char_u *name, int perm);
-int os_file_exists(const char_u *name);
 
 #endif  // NEOVIM_OS_OS_H