PCM Development/Documentation

This pages describes the documentation for developing the PCM. See PCM Documentation for information on the PCM concepts and usage.

Code documentation

Code has to be commented with Javadoc as explained here. All source code elements, including packages, should be documented.

If you add new SVN projects, be sure to document them shortly in the main code folder (see SVN-Regeln#Allgemeines) and on the PCM Code Overview here in the wiki.

Meta model documentation

The meta models (e.g. the PCM) are documented directly in the RSA models. From there, a html or pdf document can be generated automatically and be used as a reference.

• Die Doku gehört in das Properties-Tab unter "Documentation" im RSA
• Bei der Doku von bestehenden Elementen beachtet bitte, was bereits im alten TechReport und in den Dissertationen von Heiko und Steffen geschrieben wurde (die Doku sollte nicht schrumpfen).
• Dokumentiert werden sollten
  • Pakete (Überblick vermitteln; Relation zu anderen Paketen / Unterpaketen)
  • Klassen (Semantik genau erklären; auf Unterschiede zu ähnlichen Klassen hinweisen; bspw. LoopAction vs. CollectionIterator)
  • Assoziationen (Semantik; Begründungen zu Navigationsrichtungen, etc.)
  • Entwurfentscheidungen (Alternativen + Entscheidungen)
• Die Doku sollte in allen Fällen eine Erklärung bieten und dazu geeignet sein, später in einem Textdokument zu erscheinen, das

veröffentlicht wird (als Ersatz für den TechReport zum PCM). So ist ein Kommentar zu "Entity" à la "The PCM entity class" nutzlos. Bitte präzise und in ganzen Sätzen schreiben.

• Das Layout von Diagrammen sollte sorgfältig sein, da die Diagramme mit in das jeweils generierte Ergebnisdokument aufgenommen

werden sollen. Linien die quer über das Bild gehen und komplett überladene Diagramme bitte abstellen. Das Autolayout ist dabei im Allgemeinen keine Option. Platziert Basisklassen tendenziell oben in den Bildern und Entitäten mit vielen Assoziationen nebeneinander.

Further documentation

For further documentation, such as requirement documents, slides, architecture overview, etc, each SVN project (see SVN-Regeln#Allgemeines) can have a doc folder. In that folder, any further documentation for the project is stored.

Information on this level should be quite high-level. If information is more fine grained and only concerns a single plugin project or a single package, it should probably go into a Javadoc package documentation as described above.