g_app_launch_context_get_startup_notify_id

[Gian Mario Tagliaretti-3]

While writing python bindings for gio I've run into a problem with
g_app_launch_context_get_startup_notify_id.

the doc doesn't state that the list of files needs to be a Glist of
GFile, so I was using uris in the GList to test the bindings.

Another similar function g_app_launch_context_get_display accepts a
GList of uris or better its implementation in gdk
(GdkAppLaunchContext) since the "files" param is never used
internally.

g_app_launch_context_get_startup_notify_id in GdkAppLaunchContext
(_gdk_windowing_get_startup_notify_id) needs to use a GFile,
specifically the function get_icon in gdkapplaunchcontext-x11.c

So the problem is... should be a GFile always used for consistency or
it's just enough to state in the docs that
g_app_launch_context_get_startup_notify_id needs a Glist of GFiles?

I hope I made myself clear enough.

cheers
--
Gian Mario Tagliaretti
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Matthias Clasen-2]

On Sat, Jul 5, 2008 at 6:50 PM, Gian Mario Tagliaretti <gianmt@...> wrote:

> While writing python bindings for gio I've run into a problem with
> g_app_launch_context_get_startup_notify_id.
>
> the doc doesn't state that the list of files needs to be a Glist of
> GFile, so I was using uris in the GList to test the bindings.
>
> Another similar function g_app_launch_context_get_display accepts a
> GList of uris or better its implementation in gdk
> (GdkAppLaunchContext) since the "files" param is never used
> internally.
>
> g_app_launch_context_get_startup_notify_id in GdkAppLaunchContext
> (_gdk_windowing_get_startup_notify_id) needs to use a GFile,
> specifically the function get_icon in gdkapplaunchcontext-x11.c
>
> So the problem is... should be a GFile always used for consistency or
> it's just enough to state in the docs that
> g_app_launch_context_get_startup_notify_id needs a Glist of GFiles?

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


Matthias
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Gian Mario Tagliaretti-3]

On Sun, Jul 6, 2008 at 1:16 AM, Matthias Clasen
<matthias.clasen@...> 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
--
Gian Mario Tagliaretti
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Murray Cumming]

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@...> 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@...
www.murrayc.com
www.openismus.com

_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Gian Mario Tagliaretti-3]

On Mon, Jul 7, 2008 at 1:33 PM, Murray Cumming <murrayc@...> wrote:

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

In this particular case (launch and launch_uris) I didn't add an
explanation because the long description already tells you that both
are optional (and why), but I agree with you, there are some places
where the doc doesn't tell you if a parameter can be NULL and if it
does sometimes it doesn't tell you why.

cheers
--
Gian Mario Tagliaretti
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Murray Cumming]

On Mon, 2008-07-07 at 13:49 +0200, Gian Mario Tagliaretti wrote:
> On Mon, Jul 7, 2008 at 1:33 PM, Murray Cumming <murrayc@...> wrote:
>
> > And when documenting that a parameter can be NULL, it's best to say what
> > that would mean.
>
> In this particular case (launch and launch_uris) I didn't add an
> explanation because the long description already tells you that both
> are optional (and why),

You appear to be talking about function such as
g_app_info_launch_uris().

I thought we were talking about
g_app_launch_context_get_startup_notify_id() and
g_app_launch_context_get_display(). They do not say what their
parameters do.

/**
 * g_app_launch_context_get_startup_notify_id:
 * @context: a #GAppLaunchContext
 * @info: a #GAppInfo
 * @files: a #GList of of #GFile objects
 *
 * Initiates startup notification for the application and returns the
 * DESKTOP_STARTUP_ID for the launched operation, if supported.
 *
 * Startup notification IDs are defined in the <ulink
 *
url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
 * FreeDesktop.Org Startup Notifications standard</ulink>.
 *
 * Returns: a startup notification ID for the application, or %NULL if
 *     not supported.
 **/
char *
g_app_launch_context_get_startup_notify_id (GAppLaunchContext *context,
                                            GAppInfo          *info,
                                            GList             *files)


I hate how often our documentation even sometimes just says "@thing: a
#GThing".


>  but I agree with you, there are some places
> where the doc doesn't tell you if a parameter can be NULL and if it
> does sometimes it doesn't tell you why.
>
> cheers
--
murrayc@...
www.murrayc.com
www.openismus.com

_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Matthias Clasen-2]

On Mon, Jul 7, 2008 at 8:02 AM, Murray Cumming <murrayc@...> wrote:

> I thought we were talking about
> g_app_launch_context_get_startup_notify_id() and
> g_app_launch_context_get_display(). They do not say what their
> parameters do.

These functions are basically implementation details and are called in
the process of
a launch operation, so the files parameter is supposed to take the
files that are passed
as arguments to the launched application. It is really not very useful
to call these function
outside of a launch operation. The docs should probably say so.


> I hate how often our documentation even sometimes just says "@thing: a
> #GThing".

I typically use this pattern when documenting the "this" parameter of
an object method.
What else would you say there ?
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Murray Cumming]

On Mon, 2008-07-07 at 10:38 -0400, Matthias Clasen wrote:

> On Mon, Jul 7, 2008 at 8:02 AM, Murray Cumming <murrayc@...> wrote:
>
> > I thought we were talking about
> > g_app_launch_context_get_startup_notify_id() and
> > g_app_launch_context_get_display(). They do not say what their
> > parameters do.
>
> These functions are basically implementation details and are called in
> the process of
> a launch operation, so the files parameter is supposed to take the
> files that are passed
> as arguments to the launched application. It is really not very useful
> to call these function
> outside of a launch operation. The docs should probably say so.

OK. I might try to improve the documentation if nobody else does it
first.

> > I hate how often our documentation even sometimes just says "@thing: a
> > #GThing".
>
> I typically use this pattern when documenting the "this" parameter of
> an object method.
> What else would you say there ?

Yes, for "this" parameters there isn't much more to say. In fact, I
think they should have special status in gtk-doc syntax so you don't
even need to write that.

Murray


_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

[Gian Mario Tagliaretti-3]

On Mon, Jul 7, 2008 at 2:02 PM, Murray Cumming <murrayc@...> wrote:

>> In this particular case (launch and launch_uris) I didn't add an
>> explanation because the long description already tells you that both
>> are optional (and why),
>
> You appear to be talking about function such as
> g_app_info_launch_uris().

Yep I'm talking about those ones since they are on the patch which
I've attached to the previous list.

> I thought we were talking about
> g_app_launch_context_get_startup_notify_id() and
> g_app_launch_context_get_display().

We were talking _also_ about these ones, they are all in the patch,
patch that has been forgotten talking about other things.

Can I commit?

cheers
--
Gian Mario Tagliaretti
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

hi,

Murray Cumming schrieb:

> On Mon, 2008-07-07 at 10:38 -0400, Matthias Clasen wrote:
>> On Mon, Jul 7, 2008 at 8:02 AM, Murray Cumming <murrayc@...> wrote:
>>
>>> I thought we were talking about
>>> g_app_launch_context_get_startup_notify_id() and
>>> g_app_launch_context_get_display(). They do not say what their
>>> parameters do.
>> These functions are basically implementation details and are called in
>> the process of
>> a launch operation, so the files parameter is supposed to take the
>> files that are passed
>> as arguments to the launched application. It is really not very useful
>> to call these function
>> outside of a launch operation. The docs should probably say so.
>
> OK. I might try to improve the documentation if nobody else does it
> first.
>
>>> I hate how often our documentation even sometimes just says "@thing: a
>>> #GThing".
>> I typically use this pattern when documenting the "this" parameter of
>> an object method.
>> What else would you say there ?
>
> Yes, for "this" parameters there isn't much more to say. In fact, I
> think they should have special status in gtk-doc syntax so you don't
> even need to write that.
>
> Murray

For those who are not afraid of perl, patches welcome. I think its a good idea.
gtk-doc could use a default string if this/self is not documented. I guess the
only challenge is to reliably recognize those.

Stefan
_______________________________________________
gtk-devel-list mailing list
gtk-devel-list@...
http://mail.gnome.org/mailman/listinfo/gtk-devel-list