spawn: Do not export unnecessary API

Hide spawn_get_program_name(), spawn_async_with_pipes() and
spawn_get_exit_status_cb(), which are not used by anyone else and
should not be part of the plugin API unless explicitly required.

See http://lists.geany.org/pipermail/devel/2015-June/thread.html#9521

Note: this duplicates some documentation when a now hidden function was
referred to.

NEWS

@@ -129,11 +129,9 @@ Geany 1.25 (unreleased)
     * Add pseudo-unique document IDs through GeanyDocument::id and
       document_find_by_id(). This is a safer API for keeping a reference
       to a document for a long time (PR#256).
-    * Add convenient and portable spawning API: spawn_sync()
-      spawn_async(), spawn_async_with_pipes(), spawn_with_callbacks(),
-      spawn_kill_process(), spawn_get_program_name(),
-      spawn_check_command(), spawn_write_data(),
-      spawn_get_exit_status_cb() (PR#441, Dimitar Zhekov).
+    * Add convenient and portable spawning API: spawn_sync(), spawn_async(),
+      spawn_with_callbacks(), spawn_kill_process(), spawn_check_command(),
+      spawn_write_data() (PR#441, Dimitar Zhekov).
     * plugin_signal_connect() is now safe to use also with objects
       destroyed before unloading the plugin.
     * Add document_reload_force() to replace document_reload_file().

src/spawn.c

@@ -76,7 +76,7 @@
 #define G_IO_FAILURE (G_IO_ERR | G_IO_HUP | G_IO_NVAL)  /* always used together */
 
 
-/**
+/*
  *  Checks whether a command line is syntactically valid and extracts the program name from it.
  *
  *  All OS:
@@ -88,7 +88,7 @@
  *  Windows:
  *     - leading carriage returns are skipped too
  *     - a quoted program name must be entirely inside the quotes. No "C:\Foo\Bar".pdf or
- *	   "C:\Foo\Bar".bat, which would be executed by Windows as C:\Foo\Bar.exe
+ *       "C:\Foo\Bar".bat, which would be executed by Windows as C:\Foo\Bar.exe
  *     - an unquoted program name may not contain spaces. Foo Bar Qux will not be considered
  *       "Foo Bar.exe" Qux or "Foo Bar Qux.exe", depending on what executables exist, as
  *       Windows normally does.
@@ -100,11 +100,8 @@
  *  @param error return location for error.
  *
  *  @return allocated string with the program name on success, @c NULL on error.
- *
- *  @since 1.25
- **/
-GEANY_API_SYMBOL
-gchar *spawn_get_program_name(const gchar *command_line, GError **error)
+ */
+static gchar *spawn_get_program_name(const gchar *command_line, GError **error)
 {
 	gchar *program;
 
@@ -206,7 +203,24 @@ gchar *spawn_get_program_name(const gchar *command_line, GError **error)
 /**
  *  Checks whether a command line is valid.
  *
- *  Checks if @a command_line is syntactically valid using @c spawn_get_program_name().
+ *  Checks if @a command_line is syntactically valid.
+ *
+ *  All OS:
+ *     - any leading spaces, tabs and new lines are skipped
+ *     - an empty command is invalid
+ *  Unix:
+ *     - the standard shell quoting and escaping rules are used, see @c g_shell_parse_argv()
+ *     - as a consequence, an unqouted # at the start of an argument comments to the end of line
+ *  Windows:
+ *     - leading carriage returns are skipped too
+ *     - a quoted program name must be entirely inside the quotes. No "C:\Foo\Bar".pdf or
+ *       "C:\Foo\Bar".bat, which would be executed by Windows as C:\Foo\Bar.exe
+ *     - an unquoted program name may not contain spaces. Foo Bar Qux will not be considered
+ *       "Foo Bar.exe" Qux or "Foo Bar Qux.exe", depending on what executables exist, as
+ *       Windows normally does.
+ *     - the program name must be separated from the arguments by at least one space or tab
+ *     - the standard Windows quoting and escaping rules are used: double quote is escaped with
+ *       backslash, and any literal backslashes before a double quote must be duplicated.
  *
  *  If @a execute is TRUE, also checks, using @c g_find_program_in_path(), if the program
  *  specified in @a command_line exists and is executable.
@@ -453,7 +467,7 @@ static void spawn_append_argument(GString *command, const char *text)
 #endif /* G_OS_WIN32 */
 
 
-/**
+/*
  *  Executes a child program asynchronously and setups pipes.
  *
  *  This is the low-level spawning function. Please use @c spawn_with_callbacks() unless
@@ -478,11 +492,8 @@ static void spawn_append_argument(GString *command, const char *text)
  *  @param error return location for error.
  *
  *  @return @c TRUE on success, @c FALSE on error.
- *
- *  @since 1.25
- **/
-GEANY_API_SYMBOL
-gboolean spawn_async_with_pipes(const gchar *working_directory, const gchar *command_line,
+ */
+static gboolean spawn_async_with_pipes(const gchar *working_directory, const gchar *command_line,
 	gchar **argv, gchar **envp, GPid *child_pid, gint *stdin_fd, gint *stdout_fd,
 	gint *stderr_fd, GError **error)
 {
@@ -592,8 +603,19 @@ gboolean spawn_async_with_pipes(const gchar *working_directory, const gchar *com
 /**
  *  Executes a child asynchronously.
  *
- *  See @c spawn_async_with_pipes() for a full description; this function simply calls
- *  @c g_spawn_async_with_pipes() without any pipes.
+ *  A command line or an argument vector must be passed. If both are present, the argument
+ *  vector is appended to the command line. An empty command line is not allowed.
+ *
+ *  If a @a child_pid is passed, it's your responsibility to invoke @c g_spawn_close_pid().
+ *
+ *  @param working_directory child's current working directory, or @c NULL.
+ *  @param command_line child program and arguments, or @c NULL.
+ *  @param argv child's argument vector, or @c NULL.
+ *  @param envp child's environment, or @c NULL.
+ *  @param child_pid return location for child process ID, or @c NULL.
+ *  @param error return location for error.
+ *
+ *  @return @c TRUE on success, @c FALSE on error.
  *
  *  @since 1.25
  **/
@@ -1043,14 +1065,11 @@ static void spawn_append_gstring_cb(GString *string, GIOCondition condition, gpo
 }
 
 
-/**
+/*
  *  Convinience @c GChildWatchFunc callback that copies the child exit status into a gint
  *  pointed by @a exit_status.
- *
- *  @since 1.25
- **/
-GEANY_API_SYMBOL
-void spawn_get_exit_status_cb(G_GNUC_UNUSED GPid pid, gint status, gpointer exit_status)
+ */
+static void spawn_get_exit_status_cb(G_GNUC_UNUSED GPid pid, gint status, gpointer exit_status)
 {
 	*(gint *) exit_status = status;
 }

src/spawn.h

@@ -35,16 +35,10 @@
 
 G_BEGIN_DECLS
 
-gchar *spawn_get_program_name(const gchar *command_line, GError **error);
-
 gboolean spawn_check_command(const gchar *command_line, gboolean execute, GError **error);
 
 gboolean spawn_kill_process(GPid pid, GError **error);
 
-gboolean spawn_async_with_pipes(const gchar *working_directory, const gchar *command_line,
-	gchar **argv, gchar **envp, GPid *child_pid, gint *stdin_fd, gint *stdout_fd,
-	gint *stderr_fd, GError **error);
-
 gboolean spawn_async(const gchar *working_directory, const gchar *command_line, gchar **argv,
 	gchar **envp, GPid *child_pid, GError **error);
 
@@ -100,8 +94,6 @@ typedef struct _SpawnWriteData
 
 gboolean spawn_write_data(GIOChannel *channel, GIOCondition condition, SpawnWriteData *data);
 
-void spawn_get_exit_status_cb(GPid pid, gint status, gpointer exit_status);
-
 gboolean spawn_sync(const gchar *working_directory, const gchar *command_line, gchar **argv,
 	gchar **envp, SpawnWriteData *stdin_data, GString *stdout_data, GString *stderr_data,
 	gint *exit_status, GError **error);