Proposal on how to handle java doc @since tags and related

[Matt Sicker <bo...@gmail.com>]

This is more important for public APIs, but adding @since version tags are
helpful for users who come across a random version of the docs (or the
latest version) and are unsure if it applies to what they're using. It's
also nifty for documenting the evolution of an API.

Anyways, one issue I've seen come up several times in not knowing the right
version to put in. I've had to change version tags in a branch or elsewhere
multiple times before merging or releasing, for example. A simple way to
fix this would be to use the version number "TODO" when adding new APIs.
Then we could even do an automatic update when releasing that changes
@version TODO to the release version.

Ideally, I'd like to see this sort of thing be embraced by plugins as well.
My dream here would be that as a plugin author, I can add java docs to it
and have proper plugin documentation generated as well. This would also
include the version it was added (or various parameters and such). That's
another documentation point we lack for users who aren't fully upgraded.

-- 
Matt Sicker <bo...@gmail.com>

Re: Proposal on how to handle java doc @since tags and related

[Matt Sicker <bo...@gmail.com>]

That might be a better word to use just to avoid IntelliJ flagging it on
commit. :)

On 2 May 2018 at 13:12, Remko Popma <re...@gmail.com> wrote:

> Good idea.
> At work we use version NEXT in a similar way. Works quite well.
>
> Remko
>
> (Shameless plug) Every java main() method deserves http://picocli.info
>
> > On May 2, 2018, at 17:57, Matt Sicker <bo...@gmail.com> wrote:
> >
> > This is more important for public APIs, but adding @since version tags
> are
> > helpful for users who come across a random version of the docs (or the
> > latest version) and are unsure if it applies to what they're using. It's
> > also nifty for documenting the evolution of an API.
> >
> > Anyways, one issue I've seen come up several times in not knowing the
> right
> > version to put in. I've had to change version tags in a branch or
> elsewhere
> > multiple times before merging or releasing, for example. A simple way to
> > fix this would be to use the version number "TODO" when adding new APIs.
> > Then we could even do an automatic update when releasing that changes
> > @version TODO to the release version.
> >
> > Ideally, I'd like to see this sort of thing be embraced by plugins as
> well.
> > My dream here would be that as a plugin author, I can add java docs to it
> > and have proper plugin documentation generated as well. This would also
> > include the version it was added (or various parameters and such). That's
> > another documentation point we lack for users who aren't fully upgraded.
> >
> > --
> > Matt Sicker <bo...@gmail.com>
>



-- 
Matt Sicker <bo...@gmail.com>

Re: Proposal on how to handle java doc @since tags and related

[Remko Popma <re...@gmail.com>]

Good idea. 
At work we use version NEXT in a similar way. Works quite well. 

Remko

(Shameless plug) Every java main() method deserves http://picocli.info

> On May 2, 2018, at 17:57, Matt Sicker <bo...@gmail.com> wrote:
> 
> This is more important for public APIs, but adding @since version tags are
> helpful for users who come across a random version of the docs (or the
> latest version) and are unsure if it applies to what they're using. It's
> also nifty for documenting the evolution of an API.
> 
> Anyways, one issue I've seen come up several times in not knowing the right
> version to put in. I've had to change version tags in a branch or elsewhere
> multiple times before merging or releasing, for example. A simple way to
> fix this would be to use the version number "TODO" when adding new APIs.
> Then we could even do an automatic update when releasing that changes
> @version TODO to the release version.
> 
> Ideally, I'd like to see this sort of thing be embraced by plugins as well.
> My dream here would be that as a plugin author, I can add java docs to it
> and have proper plugin documentation generated as well. This would also
> include the version it was added (or various parameters and such). That's
> another documentation point we lack for users who aren't fully upgraded.
> 
> -- 
> Matt Sicker <bo...@gmail.com>