Re: g_app_launch_context_get_startup_notify_id

[Murray Cumming <murrayc murrayc com>]

More importantly, the documentation doesn't tell me what on earth that
list of files is used for in g_app_launch_context_get_display() and
g_app_launch_context_get_startup_notify_id(). I shouldn't have to guess.
http://library.gnome.org/devel/gio/unstable/GAppInfo.html#g-app-launch-context-get-startup-notify-id

And when documenting that a parameter can be NULL, it's best to say what
that would mean.

On Sun, 2008-07-06 at 11:38 +0200, Gian Mario Tagliaretti wrote:
> On Sun, Jul 6, 2008 at 1:16 AM, Matthias Clasen
> <matthias clasen gmail com> wrote:
> 
> Matthias,
> 
> > Both functions (get_display and get_startup_notify) take a list of GFiles.
> > The documentation should be clarified.
> > Although I honestly have no idea what use get_display could make of
> > the files....
> 
> I've seen your commit to the docs but I'm afraid there is a little
> mistake (@ instead of #) and you didn't commit the same fix for
> get_startup_notify_id.
> Moreover also launch and launch_uris deserve a little clarification in
> the docs, files and launch_context can be NULL.
> 
> Here is a patch, ok to commit?
> 
> Index: gio/gappinfo.c
> ===================================================================
> --- gio/gappinfo.c	(revision 7166)
> +++ gio/gappinfo.c	(working copy)
> @@ -393,8 +393,8 @@
>  /**
>   * g_app_info_launch:
>   * @appinfo: a #GAppInfo.
> - * @files: a #GList of #GFile objects.
> - * @launch_context: a #GAppLaunchContext.
> + * @files: a #GList of #GFile objects or %NULL.
> + * @launch_context: a #GAppLaunchContext or %NULL.
>   * @error: a #GError.
>   *
>   * Launches the application. Passes @files to the launched application
> @@ -476,8 +476,8 @@
>  /**
>   * g_app_info_launch_uris:
>   * @appinfo: a #GAppInfo.
> - * @uris: a #GList containing URIs to launch.
> - * @launch_context: a #GAppLaunchContext.
> + * @uris: a #GList containing URIs to launch or %NULL.
> + * @launch_context: a #GAppLaunchContext or %NULL.
>   * @error: a #GError.
>   *
>   * Launches the application. Passes @uris to the launched application
> @@ -604,7 +604,7 @@
>   * g_app_launch_context_get_display:
>   * @context: a #GAppLaunchContext.
>   * @info: a #GAppInfo.
> - * @files: a #GList of @GFile<!-- -->s.
> + * @files: a #GList of #GFile<!-- -->s.
>   *
>   * Gets the display string for the display. This is used to ensure new
>   * applications are started on the same display as the launching
> @@ -634,7 +634,7 @@
>   * g_app_launch_context_get_startup_notify_id:
>   * @context: a #GAppLaunchContext.
>   * @info: a #GAppInfo.
> - * @files: a #GList of files.
> + * @files: a #GList of #GFile<!-- -->s.
>   *
>   * Initiates startup notification for the application and returns the
>   * DESKTOP_STARTUP_ID for the launched operation, if supported.
> 
> cheers
-- 
murrayc murrayc com
www.murrayc.com
www.openismus.com