After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 723991 - Improve the display of the synopsis
Improve the display of the synopsis
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other All
: Normal normal
: 1.20
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks:
 
 
Reported: 2014-02-10 00:47 UTC by William Jon McCann
Modified: 2014-02-12 17:36 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Display hierarchy/interfaces/etc under the properties and signals (1012 bytes, patch)
2014-02-10 00:48 UTC, William Jon McCann
none Details | Review
Split Functions out from other types of declarations (8.00 KB, patch)
2014-02-10 00:48 UTC, William Jon McCann
none Details | Review
Use a table for the function synopsis (3.00 KB, patch)
2014-02-10 00:48 UTC, William Jon McCann
none Details | Review
Use tables for properties synopsis (3.61 KB, patch)
2014-02-10 00:48 UTC, William Jon McCann
none Details | Review
Use a table for signal synopsis (4.23 KB, patch)
2014-02-10 00:48 UTC, William Jon McCann
none Details | Review
Place types and values after signals (978 bytes, patch)
2014-02-10 00:48 UTC, William Jon McCann
none Details | Review
Display hierarchy/interfaces/etc under the properties and signals (1012 bytes, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Split Functions out from other types of declarations (7.65 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Use a table for the function synopsis (3.28 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Use tables for properties synopsis (4.07 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Use a table for signal synopsis (6.83 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Place types and values after signals (978 bytes, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Add language attribute to program listings (3.49 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Add space between type and * in properties (1.21 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Adjust how function parameters are displayed (4.39 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Use a table for enum members (2.90 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Use a table for struct members (3.44 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review
Use a table for union members (3.16 KB, patch)
2014-02-10 20:04 UTC, William Jon McCann
committed Details | Review

Description William Jon McCann 2014-02-10 00:47:59 UTC
Currently the synopsis is a bit hard to use. There is quite a bit jumbled into
it. Signals and Properties have their own headings but functions do not. The
display is in a very C language specific format. Not only is that not great
since we're trying to support multiple bindings it adds a lot of syntax
that just adds noise to the output.

Attached are patches that add a new Functions heading and make the display
a bit less cluttered.
Comment 1 William Jon McCann 2014-02-10 00:48:01 UTC
Created attachment 268617 [details] [review]
Display hierarchy/interfaces/etc under the properties and signals

The properties and signals are usually more interesting and
used more frequently.
Comment 2 William Jon McCann 2014-02-10 00:48:04 UTC
Created attachment 268618 [details] [review]
Split Functions out from other types of declarations

Functions are really the most useful thing in the
documenation. Currently, Signals and Properties have
their own sections but functions do not. This changes that.
Comment 3 William Jon McCann 2014-02-10 00:48:06 UTC
Created attachment 268619 [details] [review]
Use a table for the function synopsis
Comment 4 William Jon McCann 2014-02-10 00:48:09 UTC
Created attachment 268620 [details] [review]
Use tables for properties synopsis
Comment 5 William Jon McCann 2014-02-10 00:48:12 UTC
Created attachment 268621 [details] [review]
Use a table for signal synopsis
Comment 6 William Jon McCann 2014-02-10 00:48:15 UTC
Created attachment 268622 [details] [review]
Place types and values after signals
Comment 7 William Jon McCann 2014-02-10 20:04:25 UTC
Created attachment 268717 [details] [review]
Display hierarchy/interfaces/etc under the properties and signals

The properties and signals are usually more interesting and
used more frequently.
Comment 8 William Jon McCann 2014-02-10 20:04:28 UTC
Created attachment 268718 [details] [review]
Split Functions out from other types of declarations

Functions are really the most useful thing in the
documenation. Currently, Signals and Properties have
their own sections but functions do not. This changes that.
Comment 9 William Jon McCann 2014-02-10 20:04:31 UTC
Created attachment 268719 [details] [review]
Use a table for the function synopsis
Comment 10 William Jon McCann 2014-02-10 20:04:34 UTC
Created attachment 268720 [details] [review]
Use tables for properties synopsis
Comment 11 William Jon McCann 2014-02-10 20:04:37 UTC
Created attachment 268721 [details] [review]
Use a table for signal synopsis
Comment 12 William Jon McCann 2014-02-10 20:04:40 UTC
Created attachment 268722 [details] [review]
Place types and values after signals
Comment 13 William Jon McCann 2014-02-10 20:04:44 UTC
Created attachment 268723 [details] [review]
Add language attribute to program listings
Comment 14 William Jon McCann 2014-02-10 20:04:47 UTC
Created attachment 268724 [details] [review]
Add space between type and * in properties
Comment 15 William Jon McCann 2014-02-10 20:04:49 UTC
Created attachment 268725 [details] [review]
Adjust how function parameters are displayed

Use separate sections for parameters and results. Display
parameters as a table.
Comment 16 William Jon McCann 2014-02-10 20:04:52 UTC
Created attachment 268726 [details] [review]
Use a table for enum members
Comment 17 William Jon McCann 2014-02-10 20:04:55 UTC
Created attachment 268727 [details] [review]
Use a table for struct members
Comment 18 William Jon McCann 2014-02-10 20:04:59 UTC
Created attachment 268728 [details] [review]
Use a table for union members
Comment 19 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-11 20:02:15 UTC
The "Types and Values" section now looks a bit out of place with the boxes gone.

Also there is a regression as the #include is missing from the docs output.

One thing that I don't like some much, but do't have a good idea yet, is that we now have most sub-titles twice, but no clean indication where the toc part ends and the content starts (well it starts with "Description").
Comment 20 Stefan Sauer (gstreamer, gtkdoc dev) 2014-02-11 20:19:35 UTC
Comment on attachment 268725 [details] [review]
Adjust how function parameters are displayed

When submitting this one,
please mark #605537 as fixes as well. Can you tweak the space between the "Parameters" heading and the table (same for Returns and description). Imho it could be a little less.
Comment 21 William Jon McCann 2014-02-12 15:13:37 UTC
Attachment 268717 [details] pushed as 757b5c2 - Display hierarchy/interfaces/etc under the properties and signals
Attachment 268718 [details] pushed as b093ce8 - Split Functions out from other types of declarations
Attachment 268719 [details] pushed as 84c15bd - Use a table for the function synopsis
Attachment 268720 [details] pushed as 2cb1164 - Use tables for properties synopsis
Attachment 268721 [details] pushed as 3469633 - Use a table for signal synopsis
Attachment 268722 [details] pushed as e3b8ed5 - Place types and values after signals
Attachment 268723 [details] pushed as 0c157fa - Add language attribute to program listings
Attachment 268724 [details] pushed as 4486431 - Add space between type and * in properties
Attachment 268725 [details] pushed as ba99fc0 - Adjust how function parameters are displayed
Attachment 268726 [details] pushed as 9e0a5dc - Use a table for enum members
Attachment 268727 [details] pushed as e1a2fd5 - Use a table for struct members
Attachment 268728 [details] pushed as 36db270 - Use a table for union members