gtk:doc: dropping support for legacy return 'markup'

[Stefan Sauer <ensonic hora-obscura de>]

hi,

while the proper annotation for return values in gtk-doc is:

* ...
* Returns: foo bar
* ...

the tool also looks for lines starting with "returns " at the start of a
documentation body block (for legacy reasons). A following proper
"Returns:" tag would override the legacy returns docs. The tool will
also print a warning if the legacy return docs are used:
  "Free-form return value description in $symbol. Use `Returns:' to
avoid ambiguities."

I'd like to simplify the code and drop the support for legacy returns in
the upcomming 1.19 release for gtk-doc (see also #678094). Please take a
look at your docs and make changes if you rely on legacy returns (aka
see the warning).

Please let me know if this would cause troubles for your project.

Stefan