Nuking the @should taglet

Basically, the purpose of this post is as a follow-on from this post where the decision was made to stop recommending the @should taglet, but to maintain it’s presence in Javadoc. I would like to propose removing the taglet altogether from OpenMRS’s source code.

Rationale

  1. It has not been the recommended way to create tests for years.
  2. It is not clear that the IDE plugins required to make this annotation helpful have been maintained.
  3. The Taglet API has undergone a major revision, following the sun-setting of the internal com.sun.* classes that it used to depend on, meaning we’d have to somehow maintain the current state of the taglet API and create a version for Java 9 or later.

Way forward

I’d propose we take the following steps:

  1. Remove the ShouldTaglet class from openmrs-tools
  2. Replace all occurrences of the @should taglet in OpenMRS Javadoc with <strong>Should</strong>, allowing us to keep the data provided by this taglet in a human-readable format.

Are there any objections to this or thoughts on a better way forward, etc.?

2 Likes

Your proposal makes perfect sense!

1 Like

i absolutely agree with you @ibacher ,it will help avoid duplications & and making the OpenMRS’s source code more human readable which suits one of the aims of unit testing conventions ie good docs

I’ve created TRUNK-5703 to track this.