Merge pull request #710 'Automatically generate declarations'

1 files changed, 43 insertions, 8 deletions

diff --git a/src/nvim/os/job.c b/src/nvim/os/job.c
index c4a9c85d1d..f9f94158ae 100644
--- a/src/nvim/os/job.c
+++ b/src/nvim/os/job.c
@@ -58,23 +58,20 @@ static uint32_t job_count = 0;
 static uv_prepare_t job_prepare;
 
 // Some helpers shared in this module
-static bool is_alive(Job *job);
-static Job * find_job(int id);
-static void free_job(Job *job);
 
+#ifdef INCLUDE_GENERATED_DECLARATIONS
+# include "os/job.c.generated.h"
+#endif
 // Callbacks for libuv
-static void job_prepare_cb(uv_prepare_t *handle);
-static void read_cb(RStream *rstream, void *data, bool eof);
-static void exit_cb(uv_process_t *proc, int64_t status, int term_signal);
-static void close_cb(uv_handle_t *handle);
-static void emit_exit_event(Job *job);
 
+/// Initializes job control resources
 void job_init()
 {
   uv_disable_stdio_inheritance();
   uv_prepare_init(uv_default_loop(), &job_prepare);
 }
 
+/// Releases job control resources and terminates running jobs
 void job_teardown()
 {
   // 20 tries will give processes about 1 sec to exit cleanly
@@ -121,6 +118,19 @@ void job_teardown()
   }
 }
 
+/// Tries to start a new job.
+///
+/// @param argv Argument vector for the process. The first item is the
+///        executable to run.
+/// @param data Caller data that will be associated with the job
+/// @param stdout_cb Callback that will be invoked when data is available
+///        on stdout
+/// @param stderr_cb Callback that will be invoked when data is available
+///        on stderr
+/// @param exit_cb Callback that will be invoked when the job exits
+/// @return The job id if the job started successfully. If the the first item /
+///         of `argv`(the program) could not be executed, -1 will be returned.
+//          0 will be returned if the job table is full.
 int job_start(char **argv,
               void *data,
               rstream_cb stdout_cb,
@@ -212,6 +222,12 @@ int job_start(char **argv,
   return job->id;
 }
 
+/// Terminates a job. This is a non-blocking operation, but if the job exists
+/// it's guaranteed to succeed(SIGKILL will eventually be sent)
+///
+/// @param id The job id
+/// @return true if the stop request was successfully sent, false if the job
+///              id is invalid(probably because it has already stopped)
 bool job_stop(int id)
 {
   Job *job = find_job(id);
@@ -225,6 +241,14 @@ bool job_stop(int id)
   return true;
 }
 
+/// Writes data to the job's stdin. This is a non-blocking operation, it
+/// returns when the write request was sent.
+///
+/// @param id The job id
+/// @param data Buffer containing the data to be written
+/// @param len Size of the data
+/// @return true if the write request was successfully sent, false if the job
+///              id is invalid(probably because it has already stopped)
 bool job_write(int id, char *data, uint32_t len)
 {
   Job *job = find_job(id);
@@ -242,6 +266,9 @@ bool job_write(int id, char *data, uint32_t len)
   return true;
 }
 
+/// Runs the read callback associated with the job exit event
+///
+/// @param event Object containing data necessary to invoke the callback
 void job_exit_event(Event event)
 {
   Job *job = event.data.job;
@@ -265,11 +292,19 @@ void job_exit_event(Event event)
   }
 }
 
+/// Get the job id
+///
+/// @param job A pointer to the job
+/// @return The job id
 int job_id(Job *job)
 {
   return job->id;
 }
 
+/// Get data associated with a job
+///
+/// @param job A pointer to the job
+/// @return The job data
 void *job_data(Job *job)
 {
   return job->data;