API scanning improvement: Catagorize and attach javadoc in a generated report/doc site

[Cervator]

Goes somewhat with #3320, #3321, and #3322 which focus on the SemVer validating testing (whether a PR constitutes a major, minor, or patch change). But there is a whole other series of utility possible with this functionality: writing out the list of classes and packages that are part of the Modding API with added documentation and decoration.

With #3253 merged we have a report usable for API comparison, but it doesn't really do anything for actual modders/developers looking for API docs. See an example at https://gist.github.com/Cervator/f34259ba73f7af7e02f3f2627211b143

At this stage method and other related info has been added, but the docs variant should focus more on categorizing what each thing is (category) and how it works (javadoc)

Eventually we should make that available in a format that could be published as part of a website. But we could get there incrementally with a next version trying to classify and describe, either in plain text or some basic markdown/html.

For example: Events. At present there is an outdated wiki page at https://github.com/MovingBlocks/Terasology/wiki/Events that has a listing of a variety of events, but it was put together manually. That's bad. We need to automate it.

It would thus be ideal if the ApiScraper could be executed in doc mode to create such a list. Out of all the things on the Modding API list (we got that part) which are events (has Event in its parentage), and what is their short description (class-level javadoc)?

A link to the event in full Javadoc would be ideal, although we don't have a great permanent home for that yet. We do have Javadoc published for the engine in Jenkins so links could be made for that: http://jenkins.terasology.org/job/Terasology/javadoc/

Beyond Events there should also be extra highlighting of Systems and Components. Maybe other stuff? Unsure. But hopefully this issue will be a good primer for making more useful things :-)

To start: Check out the ApiScraper class and read through the linked issues here (and the issues/PRs they link to, etc etc etc ...)

[sudoshweta]

Hi @Cervator , I am an outreachy applicant, may I work on this issue?

[Adrijaned]

Hi @sudoshweta, feel free to start working on this. As far as I know, no one else should be doing this yet. Also, please consider joining our chat on #terasology on freenode or at discord.gg/Terasology