bug(#209): XMIR links in Program, Programs, Defect JavaDoc

[h1alexbel]

In this pull I've updated JavaDocs of Program.java, Programs.java, Defect.java, now they mention XMIR, and resources about it.

see #209

[h1alexbel]

@volodya-lombrozo please check

[volodya-lombrozo]

@h1alexbel Thank you for the contribution! Links are really helpful for developers of objectionary/lints. However, I should be honest with you: for users of objectionary/lints these links are useless.

Let's imagine a user that sees the following error:

[mandatory-home WARNING]:0 The +home meta is mandatory, but is absent

In this case, the user will rise one more issue in this repository or disable the linter completely. Checking code in this repository is the last thing user will do.

We need to show the error message together with the link to the documentation, otherwise it won't work.

[h1alexbel]

@volodya-lombrozo how about this: #214 (comment)?

[volodya-lombrozo]

@volodya-lombrozo how about this: #214 (comment)?

@h1alexbel I don't like the idea of "searching" something. I would like to see the link for each linter in a row:

1. Cryptic error [name-outside-of-abstract-object] How to fix: URL
2. Cryptic error [mandatory-home] How to fix: URL

Lints list is here: URL
XMIR docs is here: URL

But what you have suggested is already much better than what we have now.

[yegor256]

@volodya-lombrozo @h1alexbel we have two types of users:

1. writers of EO
2. users of API

The first type of users will use eo-maven-plugin (or eoc) and will see the output in text form in command line. They will see the links to "motive" pages. Now they don't, but here is the ticket for this: objectionary/eo#3800

The second type of users will use Program class from this library and will receive a list of Defect instances. We don't want to put URLs into defect.text() methods, because this is not where they belong. We should provide proper API documentation to API users, but not in runtime.

[h1alexbel]

@yegor256 @volodya-lombrozo for the second group, for the "users of API", I created this PR. I suggest to merge it, if its good enough. For the first group we will implement objectionary/eo#3800. But, as far I understand, JEO uses only lints API, so @volodya-lombrozo won't get any motives on his side, the motives only will come from eo-maven-plugin, and eoc right? WDYT?

[yegor256]

@h1alexbel yes, users of API (@volodya-lombrozo is one of them) only get a list of Defect objects. They (users) have to do some research on their own in order to understand what each defect means. The best we can do for them is provide proper Javadoc texts.

[yegor256]

@h1alexbel read this: https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html

also, run mvn site -Psite and then open the files generated in target/site/javadoc/index.html You will see how your text is formatted.

[h1alexbel]

@yegor256 getting this:

should be good I believe, or I missing something?

[yegor256]

@h1alexbel thanks!