Transcript XSDoc

XSDoc
an Extensible Wiki-based Infrastructure
for Framework Documentation
Ademar Aguiar, Gabriel David, Manuel Padilha
FEUP, INESC Porto
XSDoc, JISBD’2003
1
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).
XSDoc, JISBD’2003
2
Problems with
Framework Documentation
XSDoc, JISBD’2003
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.
Application 1
Framework code
Application 2
Application 3
abstraction
Framework code
Application
Code 2
Application
Code 1
Callbacks
Hooks
Plugins
...
XSDoc, JISBD’2003
Application
Code 3
4
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
XSDoc, JISBD’2003
5
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.
Abstraction
Selection
Development

Specialization
Integration
Reuse
Documentation is crucial for effective framework reuse.
XSDoc, JISBD’2003
6
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, JISBD’2003
7
XSDoc
infrastructure
XSDoc, JISBD’2003
8
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, JISBD’2003
9
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.
Development
environment

+
XSDoc
=
Documentation-enabled
Development environment
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
XSDoc, JISBD’2003
10
Documentation approaches

Literate programming (LP)
• suggests writing code and
documentation in a single source file,
psychologically organized for
comprehension by humans rather than
computers.
XSDoc

code
Alternatives
to LP
XSDocWiki
files source approaches merge
• single
LP
files
Java
doc
XSDoc, JISBD’2003
code
files
weave
doc
files
documentation contents
into code files
Converters
Converters files
from XML
(e.g. Javadoc, Doxygen)to XML
• multiple source approaches combine
files
contents of source files and XML contents
documentation files (e.g. copy-paste of
source code to HTML files).
tangle
mixed
files
javadoc
code
files
integrator
doc
files
doc
files
mixed
files
11
XSDoc Architecture
Java, C++,
and UML
editors
Web
browser
external
contents
XSDoc infrastructure
XSDoc plugin
for IDEs
XSDocWiki
Wiki
contents
Converters
from XML
Converters
to XML
Wiki, HTML,
and PDF
files
Contents
integration
Contents
extraction
XSDoc
Configuration
XML contents
repository
Creation
Management
XSDoc, JISBD’2003
Publishing
Presentation
12
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.
XSDoc, JISBD’2003
13
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.
XSDoc, JISBD’2003
14
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
XSDoc, JISBD’2003
15
Inline of Java source
Inline of UML
XSDoc, JISBD’2003
16
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.
XSDoc, JISBD’2003
17
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.
XSDoc, JISBD’2003
18
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, JISBD’2003
19
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, JISBD’2003
20
XSDoc plugin for Eclipse
UML models
Integrated
Documentation
Set of project
resources
Source code
XSDoc, JISBD’2003
21
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.
XSDoc, JISBD’2003
22
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 nonexistent topics.
• Topics can be associated with template documents, using predefined naming conventions.
• Example: a topic named CommandPattern can be associated with a
template document for documenting patterns.
XSDoc, JISBD’2003
23
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.
XSDoc, JISBD’2003
24
Conclusions

XSDoc helps reduce the effort to document frameworks, and objectoriented 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.
XSDoc, JISBD’2003
25
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, JISBD’2003
26
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.
XSDoc, JISBD’2003
27
Thanks!
Questions?
XSDoc, JISBD’2003
28