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().

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
- * runs). Calling it again will cause a fatal error.
+ * you automatically (by means of the [func@Gimp.MAIN] macro that every
+ * 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__  */