[xwiki-devs] [Proposal] Format for @since tags
Hi devs, I’d like to propose that we standardized on using multiple @since tags for multiple versions in order to be more semantic and not have to invent a syntax (that then needs to be followed and parsed) Instead of: @since 8.4.5, 8.3RC1 Use: @since 8.4.5 @since 8.3RC1 This is supported by the javadoc, see http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#au... Also note that our Unstable annotation checker needs to be in sync (I’ve opened http://jira.xwiki.org/browse/XCOMMONS-1071 in advance). The main rationale is that it’s more semantic to have one since per version (similar to having one author par author). WDYT? Thanks -Vincent PS: I have already made changes for commons and waiting for agreement before committing or discarding ;)
+1 On Tue, Sep 20, 2016 at 10:24 AM, Vincent Massol <[email protected]> wrote:
Hi devs,
I’d like to propose that we standardized on using multiple @since tags for multiple versions in order to be more semantic and not have to invent a syntax (that then needs to be followed and parsed)
Instead of:
@since 8.4.5, 8.3RC1
Use:
@since 8.4.5 @since 8.3RC1
This is supported by the javadoc, see http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#au...
Also note that our Unstable annotation checker needs to be in sync (I’ve opened http://jira.xwiki.org/browse/XCOMMONS-1071 in advance).
The main rationale is that it’s more semantic to have one since per version (similar to having one author par author).
WDYT?
Thanks -Vincent
PS: I have already made changes for commons and waiting for agreement before committing or discarding ;) _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Thomas Mortagne
On mar., sept. 20, 2016 at 10:24 AM, Vincent Massol <[email protected]> wrote: Hi devs, I’d like to propose that we standardized on using multiple @since tags for multiple versions in order to be more semantic and not have to invent a syntax (that then needs to be followed and parsed) Instead of: @since 8.4.5, 8.3RC1 Use: @since 8.4.5 @since 8.3RC1 This is supported by the javadoc, see http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#au... Also note that our Unstable annotation checker needs to be in sync (I’ve opened http://jira.xwiki.org/browse/XCOMMONS-1071 in advance). The main rationale is that it’s more semantic to have one since per version (similar to having one author par author). WDYT? +1, but do we list them ascending, descending, any order ? Thanks -Vincent PS: I have already made changes for commons and waiting for agreement before committing or discarding ;) _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs -- Denis Gervalle SOFTEC sa - CEO
+1 2016-09-20 10:42 GMT+02:00 Denis Gervalle <[email protected]>:
On mar., sept. 20, 2016 at 10:24 AM, Vincent Massol <[email protected]> wrote: Hi devs,
I’d like to propose that we standardized on using multiple @since tags for multiple versions in order to be more semantic and not have to invent a syntax (that then needs to be followed and parsed)
Instead of:
@since 8.4.5, 8.3RC1
Use:
@since 8.4.5 @since 8.3RC1
This is supported by the javadoc, see http://docs.oracle.com/javase/ 7/docs/technotes/tools/windows/javadoc.html#author
Also note that our Unstable annotation checker needs to be in sync (I’ve opened http://jira.xwiki.org/browse/XCOMMONS-1071 in advance).
The main rationale is that it’s more semantic to have one since per version (similar to having one author par author).
WDYT? +1, but do we list them ascending, descending, any order ?
Thanks -Vincent
PS: I have already made changes for commons and waiting for agreement before committing or discarding ;) _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs -- Denis Gervalle SOFTEC sa - CEO _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
-- Guillaume Delhumeau ([email protected]) Research & Development Engineer at XWiki SAS Committer on the XWiki.org project
On 20 Sep 2016, at 10:42, Denis Gervalle <[email protected]> wrote:
On mar., sept. 20, 2016 at 10:24 AM, Vincent Massol <[email protected]> wrote: Hi devs,
I’d like to propose that we standardized on using multiple @since tags for multiple versions in order to be more semantic and not have to invent a syntax (that then needs to be followed and parsed)
Instead of:
@since 8.4.5, 8.3RC1
Use:
@since 8.4.5 @since 8.3RC1
This is supported by the javadoc, see http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#au...
Also note that our Unstable annotation checker needs to be in sync (I’ve opened http://jira.xwiki.org/browse/XCOMMONS-1071 in advance).
The main rationale is that it’s more semantic to have one since per version (similar to having one author par author).
WDYT? +1, but do we list them ascending, descending, any order ?
haha… I don’t think we need to define an order since the version it itself representing an order. If we really want a best practice I’d propose from lower to higher (7.4.5 before 8.2.2 even though 7.4.5 could be released before 8.2.2 ;)). Thanks -Vincent
Thanks -Vincent
PS: I have already made changes for commons and waiting for agreement before committing or discarding ;)
+1 Thanks, Marius On Tue, Sep 20, 2016 at 11:24 AM, Vincent Massol <[email protected]> wrote:
Hi devs,
I’d like to propose that we standardized on using multiple @since tags for multiple versions in order to be more semantic and not have to invent a syntax (that then needs to be followed and parsed)
Instead of:
@since 8.4.5, 8.3RC1
Use:
@since 8.4.5 @since 8.3RC1
This is supported by the javadoc, see http://docs.oracle.com/javase/ 7/docs/technotes/tools/windows/javadoc.html#author
Also note that our Unstable annotation checker needs to be in sync (I’ve opened http://jira.xwiki.org/browse/XCOMMONS-1071 in advance).
The main rationale is that it’s more semantic to have one since per version (similar to having one author par author).
WDYT?
Thanks -Vincent
PS: I have already made changes for commons and waiting for agreement before committing or discarding ;) _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
Seems everyone agrees. I’ve now documented it at http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HUseone40sincepe... Let’s apply it now! :) Thanks -Vincent
On 20 Sep 2016, at 10:24, Vincent Massol <[email protected]> wrote:
Hi devs,
I’d like to propose that we standardized on using multiple @since tags for multiple versions in order to be more semantic and not have to invent a syntax (that then needs to be followed and parsed)
Instead of:
@since 8.4.5, 8.3RC1
Use:
@since 8.4.5 @since 8.3RC1
This is supported by the javadoc, see http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#au...
Also note that our Unstable annotation checker needs to be in sync (I’ve opened http://jira.xwiki.org/browse/XCOMMONS-1071 in advance).
The main rationale is that it’s more semantic to have one since per version (similar to having one author par author).
WDYT?
Thanks -Vincent
PS: I have already made changes for commons and waiting for agreement before committing or discarding ;)
participants (5)
-
Denis Gervalle -
Guillaume Delhumeau -
Marius Dumitru Florea -
Thomas Mortagne -
Vincent Massol