1. XSDoc, JISBD’2003 1 XSDoc an Extensible Wiki-based Infrastructure for Framework Documentation Ademar Aguiar, Gabriel David, Manuel Padilha FEUP, INESC Porto

2. XSDoc, JISBD’2003 2 Overview n Research Issue: framework documentation Object-oriented frameworks are a powerful reuse technique, but they are often difficult to learn and understand by first-time users. Good documentation helps developers reuse frameworks, but it is hard, costly and tiresome to produce without appropriate tools. n Contribution: the XSDoc tool XSDoc is an extensible wiki-based tool specifically designed to support framework documentation activities. XSDoc provides a simple web-based documentation environment that helps create and integrate typical framework documentation contents (text, models, code).

3. XSDoc, JISBD’2003 3 Problems with Framework Documentation

4. XSDoc, JISBD’2003 4 Frameworks are powerful n Frameworks are a powerful reuse technique that enables reuse of code and reuse of design. n When combined with components and patterns, frameworks are considered the most promising current technology supporting large-scale reuse. Application 1Application 2 Application 3 Application Code 2 Application Code 3 Framework code Application Code 1 abstraction Callbacks Hooks Plugins... Framework code

5. XSDoc, JISBD’2003 5 Frameworks are hard to learn n We don’t reuse what we don’t know, what we don’t understand, or what seems to be difficult to reuse. n To reuse a framework, we first have to invest time on looking for it, understanding it, and learning how to use it. n But frameworks are often difficult to learn and understand: high complexity many levels of abstraction obscure interdependencies behavior is only partially implemented

6. XSDoc, JISBD’2003 6 Frameworks require documentation n Without good documentation, frameworks are hard to master by first-time users, requiring lengthy learning curves that may compromise their major reuse advantages. n Documentation helps developers achieve the degree of understanding they need to reuse, ie, to select, to specialize, and to integrate artifacts. n Documentation is crucial for effective framework reuse. AbstractionSelectionSpecializationIntegration Development Reuse

7. XSDoc, JISBD’2003 7 Frameworks are difficult to document n Frameworks are at least an order of magnitude more difficult to document than applications or libraries: many different styles of documents; different notations to represent contents; contents are created by different kinds of authors; different audiences must be addressed; contents change very rapidly, specially during development, what requires continuous review of the documentation; a lot of information must be created, consolidated and maintained in consistency; n The support of tools and methods able to cope with such complexity is mandatory!

8. XSDoc, JISBD’2003 8 XSDoc infrastructure

9. XSDoc, JISBD’2003 9 XSDoc Overview n XSDoc means eXtensible Software Documentation. n XSDoc is a documentation infrastructure based on XML and WikiWikiWeb. n XSDoc has been initially motivated to support an approach to framework documentation inspired on the minimalist instruction theory. n XSDoc is extensible and easy to integrate in most development environments: from simple shell-based environments to sophisticated open integrated development environments (Eclipse, Together,...)

10. XSDoc, JISBD’2003 10 XSDoc goals n Towards documentation-enabled environments To provide typical development environments (integrated or not) with tools capable to support documentation activities along the framework lifecycle. n To close the gap “development - documentation” To make documentation convenient and attractive for framework developers, by assisting developers to document while they code and design. n To be simple and economical to use and customize Development environment XSDoc + = Documentation-enabled Development environment

11. XSDoc, JISBD’2003 11 Documentation approaches n Literate programming (LP) suggests writing code and documentation in a single source file, psychologically organized for comprehension by humans rather than computers. n Alternatives to LP single source approaches merge documentation contents into code files (e.g. Javadoc, Doxygen) multiple source approaches combine contents of source files and documentation files (e.g. copy-paste of source code to HTML files). tangle weave code files doc files LP files javadoc doc files Java files integrator code files doc files mixed files code files doc files mixed files XSDoc XSDocWiki XML contents Converters from XML Converters to XML

12. XSDoc, JISBD’2003 12 Creation ManagementPublishingPresentation XSDoc infrastructure XSDoc Architecture XSDoc Configuration XSDocWiki Wiki contents Java, C++, and UML editors Converters to XML Contents integration XML contents repository Contents extraction Web browser external contents Wiki, HTML, and PDF files Converters from XML XSDoc plugin for IDEs

13. XSDoc, JISBD’2003 13 XSDocWiki n The main component of the XSDoc infrastructure is a Wiki. n The Wiki concept Originally created by Ward Cunningham para o site http://c2.com/ A wiki is a web platform that enables the collaborative edition of documents. A document is composed by topics. Each topic corresponds to a web page. Pages can be edited directly with the web browser, by everyone. Links between pages can be defined using a simple, yet powerful, automatic linking mechanism based on WikiNames (a concatenation of two capitalized words). Example: the text XSDocTool can be used to link to a page with the same name.

14. XSDoc, JISBD’2003 14 XSDocWiki features n XSDocWiki extends the typical Wiki engine with features useful for documenting object-oriented frameworks. Dynamic linking and inlining of source code (Java, C++), with rich hyperlinking of identifiers, API’s, and source code comments. Dynamic linking and inlining of UML diagrams. Instantiation and validation of XML documents. Access to version control systems (CVS repositories). Document templates (patterns, use cases, cookbooks, etc.) The present implementation was based on the VeryQuickWiki 2.5.1, a wiki engine implemented with Java/JSP/Servlets.

15. XSDoc, JISBD’2003 15 XSDocWiki examples n Inline of a Java source code fragment junit.framework.TestCase#fname n Linking to a Java source code element javaSource:junit.framework.TestCase#fname n Inline of a UML diagram junit.framework.package n Linking to a a UML diagram uml:junit.framework.package

16. XSDoc, JISBD’2003 16 Inline of Java source Inline of UML

17. XSDoc, JISBD’2003 17 XSDocWiki Benefits n Extremely simple to use. n Only requires a web-browser. n Improves team communication. n Promotes the cooperation between team elements for the incremental edition of documents. n High-availability of contents (always online!) n Easy to integrate in open IDEs.

18. XSDoc, JISBD’2003 18 XML Converters n Source code contents (Java, C++) Uses a newer version of JavaML, specially evolved in this work to cope with the requirements of XSDoc, to convert Java source code contents to XML files. Uses Doxygen to convert C++ source code contents to XML files.

19. XSDoc, JISBD’2003 19 XML Converters n UML contents Planned to fully integrate with Borland’s Together for Eclipse using SVG and XMI. Meanwhile it integrates with the Omondo’s Eclipse UML plugin using graphics files. n HTML and PDF outputs Converters are used directly from wiki files.

20. XSDoc, JISBD’2003 20 XSDoc Integration Mechanisms n Wiki-centric functional integration of tools. n Open IDE integration The integration with open IDEs is achieved using specific IDE plugins that enable the use of a web browser and the interoperation of the IDE and the XSDocWiki. n Side-by-side edition of all main kinds of contents With modern Open IDEs (Borland’s Together, IBM’s Eclipse,...) all kinds of contents (source code, UML, and documents) can be done side-by-side in a single development environment. Avoids the need to constantly switching applications during development.

21. XSDoc, JISBD’2003 21 XSDoc plugin for Eclipse Set of project resources UML models Source code Integrated Documentation

22. XSDoc, JISBD’2003 22 Using XSDoc: setup... n The usage of XSDoc is very simple and can be learned fast. n Installation XSDocWiki is distributed as a web application archive (xsdoc.war) ready to be automatically deployed and installed by Tomcat application server. n Configuration Creation and customization of wiki webs for each project to use with XSDoc. This includes adaptation of templates, definition of paths to project artifacts (source code, diagrams, etc), and user accounting.

23. XSDoc, JISBD’2003 23 Using XSDoc: contents creation... n Contents creation Source code contents and UML diagrams must be created externally to the XSDocWiki, using typical editors or development environments. Documentation contents can be edited with the XSDocWiki. The creation of new pages are triggered by following links to non- existent topics. Topics can be associated with template documents, using pre- defined naming conventions. Example: a topic named CommandPattern can be associated with a template document for documenting patterns.

24. XSDoc, JISBD’2003 24 Using XSDoc: integration, publication n Contents integration Dynamic inlining of source code, UML diagrams, and XML files. Dynamic linking to source code, UML diagrams, and XML files. Automatic linking of wiki pages based on WikiNames. n Contents publication Contents can be exported to static HTML or PDF files, using predefined XSLT’s transformers.

25. XSDoc, JISBD’2003 25 Conclusions n XSDoc helps reduce the effort to document frameworks, and object- oriented in general. n Uses very simple concepts. n Provides an easy and versatile collaborative document edition. n Is easy to integrate in development environments, including open IDEs. n Is easy to use by technical and non-technical people. n Promotes the team participation in the documentation process. n Provides easy access to documentation. n Enables a smooth integration of contents.

26. XSDoc, JISBD’2003 26 Future work n Improvement of the browsing and user-adaptive features. n Support other kinds of source code files (C#, text files). n Improve the integration with Eclipse IDE features. n Improve the features related with UML diagrams. n Integration in other open IDE’s (Together).

27. XSDoc, JISBD’2003 27 XSDoc links n XSDoc main site http://www.xsdoc.com n XSDoc sources and downloads http://xsdoc.sourceforge.net/ A first public release on sourceforge is planned for the end of 2003.

28. XSDoc, JISBD’2003 28 Thanks! Questions?