Fix JavaDoc formatting

[MrNemo64]

Currently the Javadoc format follows a pattern: author - see - since - description - parameters - throws - return
This format creates the problem that JavaDoc genertors think that the description is part of the see tag, we can see this by generating the javadoc.

Another problem with it is using formatting options that don't exists in the JavaDoc like `Marked` This JavaDoc was generated using the java 8 jdk

[lokka30]

Currently the Javadoc format follows a pattern: author - see - since - description - parameters - throws - return This format creates the problem that JavaDoc genertors think that the description is part of the see tag, we can see this by generating the javadoc. Another problem with it is using formatting options that don't exists in the JavaDoc like Marked This JavaDoc was generated using the java 8 jdk

Thanks for bringing this to my attention. I'll for sure fix the javadoc formatting throughout the resource.

However, the Marked formatting is intentional - even if they are not formatted in the JavaDoc I still find these characters useful to highlight a specific part of texts i.e. class names.

( This issue is linked to #4. )

[MrNemo64]

You can use html to mark text, this way the mark is more visual

[Geolykt]

In this case, use {@link ClassName} or {@link ClassName#fieldName} or
{@link ClassName#methodName(ArgumentClassName)}

[Jikoo]

You can also use {@code inline code} to render inline code for things like null where a link is not expected.

[lokka30]

Currently the Javadoc format follows a pattern: author - see - since - description - parameters - throws - return This format creates the problem that JavaDoc genertors think that the description is part of the see tag, we can see this by generating the javadoc. Another problem with it is using formatting options that don't exists in the JavaDoc like Marked This JavaDoc was generated using the java 8 jdk

To solve this issue, do my comments go above all of the Javadoc tags?

[MrNemo64]

First the description, then all the @

/**

• Method that calls {@link ClassName#methodName(ParameterTypes)
• @return ...
• @see ...
  */

I've written this from the mobile so the format may not be 100% good

[lokka30]

This will be worked on after #37 is completed.

[MrNemo64]

Since we now have a EconomyAPIVersion enum, maybe the @since tag could have a link to the enum entry corresponding to the version. So, for example, for something added in v1.0.0:

/**
 * ...
 * @since {@link me.lokka30.treasury.api.economy.misc.EconomyAPIVersion#VERSION_1 v1.0.0}
 */

So we have a link to that enum entry and the text is still v1.0.0.

I also think that the enum entries should be renamed. See #46.

[lokka30]

Since we now have a EconomyAPIVersion enum, maybe the @since tag could have a link to the enum entry corresponding to the version. So, for example, for something added in v1.0.0:

/**
 * ...
 * @since {@link me.lokka30.treasury.api.economy.misc.EconomyAPIVersion#VERSION_1 v1.0.0}
 */

So we have a link to that enum entry and the text is still v1.0.0.

I also think that the enum entries should be renamed. See #46.

The link is quite bulky - perhaps just a text version of the API version would be better?

@since API v1.0.0 | PLUGIN v1.0.0

[Geolykt]

Why would we want to sperate API and plugin version?

[Jikoo]

The link is quite bulky - perhaps just a text version of the API version would be better?

@since API v1.0.0 | PLUGIN v1.0.0

While I'm overall ambivalent to link/non-link status, including the plugin version doesn't make sense because the API should not be aware of implementation details.

/e Unless that was a regex or and not just an inline pipe, plugin side docs. That makes sense, yeah. Definitely plaintext plugin side.

[MrNemo64]

Since we now have a EconomyAPIVersion enum, maybe the @since tag could have a link to the enum entry corresponding to the version. So, for example, for something added in v1.0.0:

/**
 * ...
 * @since {@link me.lokka30.treasury.api.economy.misc.EconomyAPIVersion#VERSION_1 v1.0.0}
 */

So we have a link to that enum entry and the text is still v1.0.0.
I also think that the enum entries should be renamed. See #46.

The link is quite bulky - perhaps just a text version of the API version would be better?

@since API v1.0.0 | PLUGIN v1.0.0

The link is long because we class name is also long but in the documentation it would still appear as "v1.0.0" and not "me.lokka30.treasury.api.economy.misc.EconomyAPIVersion#VERSION_1"

The link is quite bulky - perhaps just a text version of the API version would be better?
@since API v1.0.0 | PLUGIN v1.0.0

While I'm overall ambivalent to link/non-link status, including the plugin version doesn't make sense because the API should not be aware of implementation details.

/e Unless that was a regex or and not just an inline pipe, plugin side docs. That makes sense, yeah. Definitely plaintext plugin side.

I agree with that. The API should not contain any type of information about the plugin or the implementations. About linking the enum, it's just an idea not much really changes by adding it or not

[lokka30]

Why would we want to sperate API and plugin version?
The API version is independent of the plugin version as changes can be made to the API but not the plugin and vice versa.

While I'm overall ambivalent to link/non-link status, including the plugin version doesn't make sense because the API should not be aware of implementation details.
/e Unless that was a regex or and not just an inline pipe, plugin side docs. That makes sense, yeah. Definitely plaintext plugin side.

I agree with that. The API should not contain any type of information about the plugin or the implementations. About linking the enum, it's just an idea not much really changes by adding it or not

Do you suggest that we only include 'api' or 'plugin' depending on which module the code is in?

Link is formatted without the classpath

Brilliant - let's use the link system then.

[MrNemo64]

Do you suggest that we only include 'api' or 'plugin' depending on which module the code is in?

Yes. The api is just that, a collection of interfaces that specify how interactions are made. If we also mention the plugin in the api module it gets confusing because you also have to think about the plugin while coding, even though you don't need to.
And what of someone implements the api but not to make a provider or use the services of the provider but to create it's own plugin?

If we also mention the plugin on the api module people can get confused because maybe the things that you said about the plugin aren't even true (they are running another plugin instead of treasury)

[lokka30]

Merging this issue with #4