[webkit-gtk] Since: tags in documentation

[Žan Doberšek]

Greetings,

resolving bug #16123 spurred some debate[1] about what value the Since: tag
in documentation should hold. There are basically two choices - the tag
could hold the unstable version in which described API first occurred
(1.5.4, 1.7.5 etc.) or it could hold the series of stable versions that
follow the series of unstable versions in which the API first occurred
(1.6, 1.8 etc).

Currently the Since: tags hold values of the unstable versions. There are
some exceptions, e.g. the complete WebKitWebWindowFeatures API contains
1.0.3 value for the Since: tags. I don't know the reasoning behind this,
though.

While using stable version series as the value would bring some degree of
clarity to documentation, in my opinion the value of unstable version gives
more information and is essential to someone who is at a given moment
constrained to using an unstable release.

Note that WebKit2 documentation does not yet have any Since: tags as API
development is still well in progress, but conclusions of this debate
should be taken into account when the tags will be making their way into
documentation.

Further steps will be done based on further opinions, so please speak up.

[1] https://bugs.webkit.org/show_bug.cgi?id=16123#c37
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-gtk/attachments/20120313/e4b4e549/attachment.html>