1 / 28

XSDoc an Extensible Wiki-based Infrastructure for Framework Documentation

XSDoc an Extensible Wiki-based Infrastructure for Framework Documentation Ademar Aguiar, Gabriel David , Manuel Padilha FEUP, INESC Porto. Overview. Research Issue: framework documentation

bonnie
Download Presentation

XSDoc an Extensible Wiki-based Infrastructure for Framework Documentation

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

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

  2. Overview • 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. • 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. Problems withFramework Documentation

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

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

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

  7. Frameworks are difficult to document • 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; • The support of tools and methods able to cope with such complexity is mandatory!

  8. XSDoc infrastructure

  9. XSDoc Overview • XSDoc means eXtensible Software Documentation. • XSDoc is a documentation infrastructure based on XML and WikiWikiWeb. • XSDoc has been initially motivated to support an approach to framework documentation inspired on the minimalist instruction theory. • 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. Development environment XSDoc Documentation-enabled Development environment + = XSDoc goals • Towards documentation-enabled environments • To provide typical development environments (integrated or not) with tools capable to support documentation activities along the framework lifecycle. • 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. • To be simple and economical to use and customize

  11. code files tangle LP files weave doc files XSDoc code files XSDocWiki doc files Java files javadoc mixed files Converters to XML Converters from XML doc files code files XML contents mixed files integrator doc files Documentation approaches • Literate programming (LP) • suggests writing code and documentation in a single source file, psychologically organized for comprehension by humans rather than computers. • 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).

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

  13. XSDocWiki • The main component of the XSDoc infrastructure is a Wiki. • 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. XSDocWiki features • 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. XSDocWiki examples • Inline of a Java source code fragment • <javaSource>junit.framework.TestCase#fname</javaSource> • Linking to a Java source code element • javaSource:junit.framework.TestCase#fname • Inline of a UML diagram • <uml>junit.framework.package</uml> • Linking to a a UML diagram • uml:junit.framework.package

  16. Inline of Java source Inline of UML

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

  18. XML Converters • 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. XML Converters • 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. • HTML and PDF outputs • Converters are used directly from wiki files.

  20. XSDoc Integration Mechanisms • Wiki-centric functional integration of tools. • 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. • 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 plugin for Eclipse UML models Integrated Documentation Set of project resources Source code

  22. Using XSDoc: setup... • The usage of XSDoc is very simple and can be learned fast. • Installation • XSDocWiki is distributed as a web application archive (xsdoc.war) ready to be automatically deployed and installed by Tomcat application server. • 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. Using XSDoc: contents creation... • 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. Using XSDoc: integration, publication • 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. • Contents publication • Contents can be exported to static HTML or PDF files, using predefined XSLT’s transformers.

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

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

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

  28. Thanks!Questions?

More Related