Bug 6268 - (int-148188) The required #include directives are not documented for Hildon
(int-148188)
: The required #include directives are not documented for Hildon
Status: RESOLVED FIXED
Product: Desktop platform
hildon-widgets
: 5.0/(2.2009.51-1)
: All Linux
: Low normal (vote)
: 5.0/(10.2010.19-1)
Assigned To: Claudio Saavedra
: hildon-libs-bugs
: http://maemo.org/api_refs/5.0/5.0-fin...
: docs
:
:
  Show dependency tree
 
Reported: 2009-11-21 15:03 UTC by Juha Koivisto
Modified: 2010-03-15 20:54 UTC (History)
2 users (show)

See Also:


Attachments


Note

You need to log in before you can comment on or make changes to this bug.


Description Juha Koivisto (reporter) 2009-11-21 15:03:11 UTC
DOCUMENTATION VERSION:
5.0-final

EXACT STEPS LEADING TO PROBLEM: 
1. Browse the Hildon Reference Manual (see URL)
2. Check the documentation e.g. for HildonButton, or likely any other class

EXPECTED OUTCOME:
The Synopsis should list the required #include directive on the first line, as
is customary in GTK+/Glib documentation

ACTUAL OUTCOME:
No #include directive is documented. The developer is left guessing which
header is needed, or has to search for this information elsewhere.

REPRODUCIBILITY:
always

EXTRA SOFTWARE INSTALLED:

OTHER COMMENTS:

User-Agent:       Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.5)
Gecko/20091112 Iceweasel/3.5.5 (like Firefox/3.5.5; Debian-3.5.5-1)
Comment 1 Andre Klapper maemo.org 2009-11-22 21:30:39 UTC
Does this cover all of the Widgets? Or also stuff that is NOT part of the
widgets?
Comment 2 Juha Koivisto (reporter) 2009-11-22 23:12:00 UTC
I'm not sure if I understood your question, but all pages that document
functions should also document which header file is needed to use them. The
same applies for widgets as well as non-widget classes (such as HildonProgram).

For GTK+, Glib and most other G* libraries the headers are specified on the
first line of the Synopsis section, see for example
http://maemo.org/api_refs/5.0/5.0-final/gtk/GtkWidget.html

In libhildon I haven't seen that for any class/widget as far as I remember. The
docs for libhildondesktop on the other hand show the headers, libhildonfm and
libnotify again not. I didn't check all of the other libraries, but likely
there may be others too where this information is missing.
Comment 3 Claudio Saavedra 2009-11-25 10:04:39 UTC
Moving to the proper component.
Comment 4 Claudio Saavedra 2009-11-25 10:06:00 UTC
(In reply to comment #2)
> In libhildon I haven't seen that for any class/widget as far as I remember. The
> docs for libhildondesktop on the other hand show the headers, libhildonfm and
> libnotify again not. I didn't check all of the other libraries, but likely
> there may be others too where this information is missing.

This bug is for libhildon, from what I understand. You'll need to file separate
a separate bug for libhildonfm. libnotify would better do with an upstream
report about this.
Comment 5 Claudio Saavedra 2009-11-25 10:35:30 UTC
commit ad85455a383f98bf7249e8d6775c40a44ec8ffc1
Author: Claudio Saavedra <csaavedra@igalia.com>
Date:   Wed Nov 25 09:34:40 2009 +0100

    Add default includes for gtkdoc-mkdb

    Fixes: NB#148188 (The required #include directives are not documented
           for Hildon)
    Fixes: MB#6268 (The required #include directives are not documented
           for Hildon)
Comment 6 Andre Klapper maemo.org 2009-12-18 13:43:06 UTC
This has been fixed in package
libhildon 2.2.8-2+0m5
which is part of the internal build version
2009.51-8
(Note: 2009 is the year, and the number after is the week.)

A future public update released with the year/week later than this internal
build version will include the fix. (This is not always already the next public
update.)
Please verify that this new version fixes the bug by marking this bug report as
VERIFIED after the public update has been released and if you have some time.


To answer popular followup questions:
 * Nokia does not announce release dates of public updates in advance.
 * There is currently no access to these internal, non-public build versions.
   A Brainstorm proposal to change this exists at
http://maemo.org/community/brainstorm/view/undelayed_bugfix_releases_for_nokia_open_source_packages-002/
Comment 7 Andre Klapper maemo.org 2010-01-14 13:40:51 UTC
(Fix not included in today's 2.2009.51-1 update => updating Version field)
Comment 8 Andre Klapper maemo.org 2010-03-15 20:54:08 UTC
Setting explicit PR1.2 milestone (so it's clearer in which public release the
fix will be available to users).

Sorry for the bugmail noise (you can filter on this message).