GNOME Bugzilla – Bug 723991
Improve the display of the synopsis
Last modified: 2014-02-12 17:36:09 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.
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.
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.
Created attachment 268619 [details] [review] Use a table for the function synopsis
Created attachment 268620 [details] [review] Use tables for properties synopsis
Created attachment 268621 [details] [review] Use a table for signal synopsis
Created attachment 268622 [details] [review] Place types and values after signals
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.
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.
Created attachment 268719 [details] [review] Use a table for the function synopsis
Created attachment 268720 [details] [review] Use tables for properties synopsis
Created attachment 268721 [details] [review] Use a table for signal synopsis
Created attachment 268722 [details] [review] Place types and values after signals
Created attachment 268723 [details] [review] Add language attribute to program listings
Created attachment 268724 [details] [review] Add space between type and * in properties
Created attachment 268725 [details] [review] Adjust how function parameters are displayed Use separate sections for parameters and results. Display parameters as a table.
Created attachment 268726 [details] [review] Use a table for enum members
Created attachment 268727 [details] [review] Use a table for struct members
Created attachment 268728 [details] [review] Use a table for union members
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 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.
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