architecture documentation, examples, cleanup

[pbrada]

Topic for KIV/SAR semester course project.

• learn and analyse CRCE internals
• create documentation of its architecture - modules, APIs, processes/flows, (use UML); data structures, persistent data formats (use whatever agreed upon)
• update build so that internal API dev docs are generated and published
• analyse, where internal APIs break rules of good API design, and create refactored versions of some (agreed upon ones)
• create/update example of "how to build a CRCE plugin"

Former documentation (https://app.assembla.com/spaces/crce/wiki) can be used as a basis.

[pbrada]

The generated JavaDocs should be put into deploy/javadoc/ folder.

[pbrada]

update:

• will be done on a separate "sar-2019" branch, off "dev"
• example plugin will be JAR indexer enumerating and counting imported packages

[pbrada]

further clarifications

• UML model for module/bundle dependencies, based on class imports
  • indicate unused modules in core, modules
• processes = mainly the filter chain management, also the concurrency
• document data structures (Resource etc) as UML (the reality of the intent as captured in https://app.assembla.com/spaces/crce/wiki/Metadata_example_-_core) + links to javadoc
• data formats = where in impl are the classes that map the data structures to database representation + where in impl are the classes that map persisted data structures to the representation provided by CRCE web service interface (XML, JSON)

[pbrada]

Review of handed-in documents and implementation: example plug-in very good, wiki ok, UML models in EnterpriseArchitect and the PDF documentation so-so at best.

Issues left to resolve: high priority

• wiki: correct links to source files on "main filter chain" page
• wiki: a separate page "how to create a plugin" needs to be added, should then link (from text) to the metadata model and filter chain pages
• wiki: replace imgur links to full-size images stored in the project files (eg arch/img folder), the wiki should be self-contained
• readme: add instructions to build javadoc

normal priority

• plugin: add javadoc comments to namespace classes, explaining what they are good for
• wiki: add link to example API sources that fit well with rules, on the "api principles" page
• wiki: unify the formatting of links to project files / source classes on all pages
• wiki: title "metadata API" is partially misleading, as the presented classes are mostly domain entities and only partly a functionality API
• wiki: consider refactoring the "persistent data" page, the db structures part may well go to the metadata description and the remainder may be left as a page ("rest format" or whatever suitable title)

[mazinvit]

All listed issues are solved.