Move documentation from function declarations to definitions

Uses a perl script to move it (scripts/movedocs.pl)

1 files changed, 40 insertions, 0 deletions

diff --git a/src/nvim/os/job.c b/src/nvim/os/job.c
index c4a9c85d1d..d19e009421 100644
--- a/src/nvim/os/job.c
+++ b/src/nvim/os/job.c
@@ -69,12 +69,14 @@ 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 +123,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 +227,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 +246,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 +271,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 +297,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;