GNOME Bugzilla – Bug 605537
Returns: listed among parameters
Last modified: 2014-02-12 17:34:15 UTC
Returns should probably be formated like Since: -- now ---------------------------------------------------------- gtkdoc_object_new () +---------------------------------------------------------------+ |GtkdocObject * gtkdoc_object_new (gchar *name);| +---------------------------------------------------------------+ Create a new instance name : the name of the new object Returns : the instance or NULL in case of an error Since 0.1 -- afterwards --------------------------------------------------- gtkdoc_object_new () +---------------------------------------------------------------+ |GtkdocObject * gtkdoc_object_new (gchar *name);| +---------------------------------------------------------------+ Create a new instance name : the name of the new object Returns the instance or NULL in case of an error Since 0.1
I am against this change. First, it's splitting hairs. Second, are you going to include an AI that will correctly rewrite all: @returns: %TRUE on success, %FALSE on failure. @returns: In case of success, the number of items is returned... @returns: If the item exists, the function returns... etc.
Third, it is customary to omit the sentence subject in the short description of a symbol, assuming the symbol name typically comes just before it so it makes sense. However, this new Returns, appearing as a normal sentence, is just bad grammar. I am not against visually separating the return value a bit in the table if you feel it's necessary. Nevertheless the documentation is written assuming it's an entry in table preceded by `Returns:'[*]. So the description can be an incomplete sentence with just the object or it can be complete sentence(s) describing what the function returns. [*] `Return value:' would be better though too verbose.
(In reply to comment #1) > I am against this change. First, it's splitting hairs. Second, are you going > to include an AI that will correctly rewrite all: > > @returns: %TRUE on success, %FALSE on failure. > > @returns: In case of success, the number of items is returned... > > @returns: If the item exists, the function returns... > > etc. It is "Returns:" and not "@returns:", @ is only for parameters/members. I also forgot the ":" in my example. All I was suggesting is to move it out of the parameter/member table. Just imagine someone has a function that has a parameter called "returns".
(In reply to comment #3) > > It is "Returns:" and not "@returns:", @ is only for parameters/members. Sorry, I was thinking in a sane syntax. > I also > forgot the ":" in my example. All I was suggesting is to move it out of the > parameter/member table. Just imagine someone has a function that has a > parameter called "returns". He'll got lowercase `returns' in typewriter-font for the parameters and title case `Returns' in roman (well, italics actually) for the return value. The return value quite stands out already and could be immediately recognized even if the function had three parameters called `returns', `Return' and `Returns'. As I said, if you feel it's confusing, change the text to `Return value'. But better, don't try to fix what isn't broken.
Fixed by #605537.