Comments (15)
In this case, use {@link ClassName}
or {@link ClassName#fieldName}
or
{@link ClassName#methodName(ArgumentClassName)}
from treasury.
You can use html to mark text, this way the mark is more visual
from treasury.
You can also use {@code inline code}
to render inline code
for things like null
where a link is not expected.
from treasury.
First the description, then all the @
/**
I've written this from the mobile so the format may not be 100% good
from treasury.
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.
from treasury.
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.
from treasury.
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
from treasury.
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)
from treasury.
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. )
from treasury.
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?
from treasury.
This will be worked on after #37 is completed.
from treasury.
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
from treasury.
Why would we want to sperate API and plugin version?
from treasury.
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.
from treasury.
Merging this issue with #4
from treasury.
Related Issues (20)
- Expanding #246
- General Javadoc Improvements
- `Response`: add method to fail with a given exception HOT 6
- `Account`: Change the return type of `retrievePermissionsMap` HOT 7
- Review API methods which do not return a Future+Response type. HOT 13
- `EconomyTransaction`: Rename some variables, getters and setters HOT 6
- `Currency`: Should we map display names against locales? HOT 3
- Responses vs Exceptions - differentiate and debate HOT 20
- `Account`: Rename `setPermission`, `hasPermission` to use a plural HOT 3
- Review methods which return TriStates but do not utilise all three possible states HOT 25
- `Account`: add another `setPermissions` method which accepts a `Map<perm, state>` HOT 2
- Change currency identifier to NamespacedKey HOT 6
- EconomyTransactionResult HOT 6
- Add abstract TreasuryException#getMessage(Locale) method
- Publish to Hangar HOT 5
- Last thoughts on Treasury v2's API? YOUR OPINION is wanted! HOT 10
- Write API Documentation in Wiki HOT 17
- Strip colours out of logging HOT 1
- Breaking Change Proposals ('Treasury v3')
- New Author HOT 7
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from treasury.