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

XSDoc, JISBD’2003 XSDoc, JISBD’2003 11

XSDocXSDocan Extensible Wiki-based an Extensible Wiki-based Infrastructure Infrastructure for Framework Documentationfor Framework Documentation

Ademar Aguiar, Gabriel David, Manuel Padilha

FEUP, INESC Porto


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).


Problems withFramework Documentation


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.

Application 1 Application

2Application 3

Application

Code 2

Application

Code 3

Framework code

Application

Code 1

abstraction

Callbacks

HooksPlugins

...

Framework code


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


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.

Abstraction Selection Specialization Integration

Development Reuse


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!


XSDoc infrastructure


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, ...)


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

Development environment XSDoc+ = Documentation-enabled

Development environment


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).

tangle

weave

code files

docfiles

LP files

javadoc docfiles

Java files

integrator

code files

docfiles

mixed files

code files

docfiles

mixed files

XSDoc

XSDocWiki

XML contents

Convertersfrom XML

Convertersto XML


Creation Management Publishing Presentation

XSDoc infrastructure

XSDoc Architecture

XSDocConfiguration

XSDocWikiWiki

contents

Java, C++, and UML

editors

Convertersto XML

Contentsintegration

XML contentsrepository

Contents extraction

Webbrowser

external contents

Wiki, HTML, and PDF

files

Convertersfrom XML

XSDoc pluginfor IDEs


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.


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.


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


Inline of Java source

Inline of UML


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.


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.


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.


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.


XSDoc plugin for Eclipse

Set of project resources

Set of project resources

UML modelsUML models

Source codeSource code

Integrated Documentation

Integrated Documentation


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.


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.


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.


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.


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).


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.


Thanks!

Questions?

Documents

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