JavaDoc + Wiki = WikiDoc - Kollaborative Dokumentationssystem für Java
Bearbeiter und Betreuer
Diese Arbeit wird bearbeitet von Jing Zhao und betreut von Christopher Oezbek und Prof. Prechelt.Diese Arbeit wurde ursprünglich begonnen von Robert Wolf.
Beschreibung
In dieser Arbeit sollen ein inline Dokumentationwerkzeug (JavaDoc oder auch Doxygen) um Wiki-Funktionalität erweitert werden. Dies würde verteilten Entwicklungsteams eine bequeme Möglichkeit zur Bearbeitung von Dokumentation geben. Besonders quelloffene Projekte wie in der Open Source und Free Software Szene würden sehr profitieren, wenn die Barriere für die Bereitstellung von Dokumentation-Patches gesenkt wird.
Requirements Analysis
- Compatible look and feel toward the original JavaDoc.
- Wiki-Capabilities
- A user should be able to modify individual documentation entries about a public programming entity.
- WikiDoc is able to translate these modifications into changes of the source document.
- This translation is done without reformatting the source document as to be robust under diff-operation.
- Authoritative-Versioning
- In contrast to the pure wiki-culture, there is an authoritative version of the source code, namely those files originally provided to WikiDoc.
- WikiDoc maintains its internal state which includes all modifications done by users in a fashion that allows the following operations for element, file and source-tree granularity:
- Show the differences between the authoritative and user-modified version.
- Accept user-modifications into authoritative version.
- Revert to authoritative version.
- It is possible to update and commit the changes of the authoritative version into a version control system.
- Log contributions
- For some projects like ClassPath it is necessary that changes that exceed a certain size are clearly connected to a registered contributor. A sign-on/sign-off mechanism will be provided, possibly linked to an existing user-database, like the own in GNU Savannah.
- For projects that just want an easy web-interface for users to modify the inline API documentation it should be possible to switch off logging.
- Performance
- Using the user-interface does not induce any human noticeable time delays beyond usual HTTP performance.
- User-Modifications are incorporated directly into the internal state and are visible for all other operations. (That means that changes don't only become visible every other hour when the whole JavaDoc is rebuild).
- Repository-Modifications (the authoritative version changed) can be updated on a hourly scale without interruptions for the user in service for a normal sized project (100 class files and 100k LOC). It should be possible to index large scale projects like the JDK within a 12 hour time-frame.
- If user actions require longer than 5 seconds of server-side processing the user is informed continuously about the progress of the operation.
- The system should run stable on current servers being able to server 20 concurrent viewer and 5 concurrent editors.
- Memory consumption is conservative but not restrictive. Aim is to run the entire system with less than 128 MB of VM memory.
- Robustness
- The behavior in abnormal cases is well defined.
- Especially taking care of conflict resolution from the wiki.
- Notification service
- Interested parties can subscribe to each element of the system to get notified when changes occur.
- Installation requirements
- The time needed for installing the system is not allowed to exceed 10 Minutes.
- The number of components required for installation (JDK, Tomcat, MySQL) is not allowed to exceed 5 and their installation must be of max. 30 min each.
- Documentation
- The source code and all systems files are documented sufficiently.
- User and adminstrator documentation is available.
- All documents that should be available to persons outside FU Berlin should be written in English.
- Optional Requirements:
- Discussion board functionality connected to a mailing-list.
- RSS-Feed for the changes that occured.
- The system is able to display tags and branched version.
- The user-modified version is under version control so that it is possible to distinguish between different modifications made to the same programming entity comment. The semantics for that would need some discussion.
Stage "Code manipulation"
A tool has to be created that can update JavaDoc comments in a selective manner. The interface should look similar to this:> updateJavadoc de/inffub/agse/wikidoc/coderewriter/test/JavadocModifyTest.Nested.html#JavadocModifyTest.Nested() "New javadoc comment"
The exact syntax for the fully qualified expression that identifies the method, attribute or class to be changed must be fully compatible to the JavaDoc syntax used for the same problem.