app, libgimp: move gimp_env_init() to a non-shipped header.

Since we consider it private, yet it's still needed in libgimp and app,
let's at least put it in a private header because there is no need for
people to try it out.

I'm also editing a bit the annotations for gimp_main() and GIMP_MAIN().

app/main.c

@@ -53,6 +53,7 @@
 #include <babl/babl.h>
 
 #include "libgimpbase/gimpbase.h"
+#include "libgimpbase/gimpbase-private.h"
 
 #include "pdb/pdb-types.h"
 

libgimp/gimp.c

@@ -152,13 +152,20 @@ static GimpStackTraceMode  stack_trace_mode      = GIMP_STACK_TRACE_NEVER;
  * @argv:         (array length=argc): the arguments
  *
  * The main plug-in function that must be called with the plug-in's
- * #GimpPlugIn subclass #GType and the 'argc' and 'argv' that are passed
+ * [class@Gimp.PlugIn] subclass #GType and the 'argc' and 'argv' that are passed
- * to the platform's main().
+ * to the platform's `main()`.
  *
- * See also: GIMP_MAIN(), #GimpPlugIn.
+ * For instance, in Python, you will want to end your plug-in with this
+ * call:
+ *
+ * ```py
+ * Gimp.main(MyPlugIn.__gtype__, sys.argv)
+ * ```
+ *
+ * For C plug-ins, use instead the [func@Gimp.MAIN] macro
  *
  * Returns: an exit status as defined by the C library,
- *          on success EXIT_SUCCESS.
+ *          on success `EXIT_SUCCESS`.
  *
  * Since: 3.0
  **/

libgimp/gimp.h

@@ -89,9 +89,11 @@ G_BEGIN_DECLS
  * A macro that expands to the appropriate main() function for the
  * platform being compiled for.
  *
- * To use this macro, simply place a line that contains just the code
+ * To use this macro, simply place a line that contains just the code:
  *
+ * ```C
  * GIMP_MAIN (MY_TYPE_PLUG_IN)
+ * ```
  *
  * at the toplevel of your file. No semicolon should be used.
  *

libgimpbase/gimpbase-private.h

@@ -23,6 +23,9 @@
 #define __GIMP_BASE_PRIVATE_H__
 
 
+#include <libgimpbase/gimpenv-private.h>
+
+
 typedef struct _GimpUnitVtable GimpUnitVtable;
 
 struct _GimpUnitVtable

libgimpbase/gimpenv-private.h

@@ -0,0 +1,35 @@
+/* LIBGIMP - The GIMP Library
+ * Copyright (C) 1995-1997 Peter Mattis and Spencer Kimball
+ *
+ * gimpenv-private.h
+ *
+ * This library is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library.  If not, see
+ * <https://www.gnu.org/licenses/>.
+ */
+
+#ifndef __GIMP_ENV_PRIVATE_H__
+#define __GIMP_ENV_PRIVATE_H__
+
+G_BEGIN_DECLS
+
+/* For information look into the C source or the html documentation */
+
+
+void          gimp_env_init                    (gboolean      plug_in);
+
+
+G_END_DECLS
+
+#endif  /*  __GIMP_ENV_PRIVATE_H__  */
+

libgimpbase/gimpenv.c

@@ -40,6 +40,7 @@
 
 #define __GIMP_ENV_C__
 #include "gimpenv.h"
+#include "gimpenv-private.h"
 #include "gimpversion.h"
 #include "gimpreloc.h"
 
@@ -99,8 +100,9 @@ const guint gimp_micro_version = GIMP_MICRO_VERSION;
  * @plug_in: must be %TRUE if this function is called from a plug-in
  *
  * You don't need to care about this function. It is being called for
- * you automatically (by means of the MAIN() macro that every plug-in
+ * you automatically (by means of the [func@Gimp.MAIN] macro that every
- * runs). Calling it again will cause a fatal error.
+ * C plug-in runs or directly with [func@Gimp.main] in binding). Calling
+ * it again will cause a fatal error.
  *
  * Since: 2.4
  */

libgimpbase/gimpenv.h

@@ -78,10 +78,6 @@ void          gimp_path_free                   (GList        *path);
 gchar       * gimp_path_get_user_writable_dir  (GList        *path) G_GNUC_MALLOC;
 
 
-/*  should be considered private, don't use!  */
-void          gimp_env_init                    (gboolean      plug_in);
-
-
 G_END_DECLS
 
 #endif  /*  __GIMP_ENV_H__  */