'SchemaDoc' - a Simple Mechanism for Commenting a Schema Would be Desirable

Further to our recent proposal for an 'Import and Change Target Namespace'
feature, as posted by my colleague Bob Schloss [1], I would like to suggest
the following additional feature:

Proposal for 'SchemaDoc' - a Simple Mechanism for Commenting a Schema

--Introduction

The current mechanism for commenting a Schema using annotations involves
the use of only two standard elements - documentation and appinfo.  It
would be much more useful if there was a mechanism similar to Sun's JavaDoc
[2], for commenting a schema using standard tags.  This could be
implemented as a 'standard' content model for the documentation element,
which schema-writers are encouraged to use.

The aim of such a mechanism would be to allow a 'SchemaDoc' tool to
automatically generate a 'rendering' of a schema, in HTML or otherwise.  Of
course this is already possible, for example using the latest beta of Xml
Spy v3.5 [3], but this information would allow additional, structured
information to be 'inserted' into the rendering.  So, for example, the
schema could be divided into virtual chapters.  (This would be useful in,
for example, the UDDI schema [4] to break it into 'Data stored' and 'SOAP
API' chapters, and possibly sub-chapters.)  In addition to this, SchemaDoc
comments would also help make a schema more readable, which is why they
would be included inside documentation, as opposed to appinfo elements.

--The Types of Comment 'tags' that Could be Present Inside a Documentation
Element

The main problem is, of course, choosing a tag set that would satisfy the
majority of users.  I would propose having a minimal tag set, based on
JavaDoc's tag set, for Schema Version 1.  As in JavaDoc, there would be two
main types of comments: comments for the entire schema, and comments for
individual schema components.  This would allow fundamental comments such
as author, and 'see also' links to be added to a schema in a standard way.
Additional tagsets could then be added in later versions of Schema.

In addition to core comments about the schema, it is this author's opinion
that it would also be useful to have a special set of tags to help comment
a schema as it is being written.  (i.e. work in progress notes.)  Of
course, this is just one of many extra 'sets' of tags that could be added,
so it is included in this proposal primarily to encourage discussion.

--Example Tag Sets

-Core Tags

The following are the core tags, based on those of JavaDoc, that it would
be beneficial to introduce straight away.

The Entire Schema

- Author
- Description
- See Also (i.e. links)
- Copyright info
- Known Bugs
- etc

Individual Components

- Virtual 'chapter' of the schema it is part of
- Author, if different to main author
- Version
- See Also (i.e. links)
- Deprecated
- Present since version...
- Description

-Work in Progress Tags

The following is an example of an additional set of tags.

The Entire Schema

- Todo List
- Issues (open, closed etc)
- Status
- Misc Comments
- etc

Individual Components - Work in Progress Tags

- largely the same as for the entire schema, but specific to this
component, as opposed to the entire schema.

--Example Syntax

<annotation>
  <documentation source="http://www.w3.org/2000/10/XMLSchema-schemadoc/">
    <author>David Bacigalupo</author>
    <description>some html...</description>
    <seeAlso type="href">http://www.example.com/...example.xsd</seeAlso>
  </documentation>
</annotation>

--Issues

1.)  How would a schema include comments from multiple tag sets?  This
could be as simple as having multiple documentation elements, each one
pointing to a different tagset namespace, although this would be
restrictive.  Ideally, the Structures Spec should be clearer on exactly how
the 'source' attribute of a documentation element is used.
2.) How many 'tags' should be included in the standard?  Anything not
included can of course be entered as text in some kind of 'miscellaneous'
tag.  Ideally for version 1 the number of tags should be small.
3.) Should it be possible to create your own schemas for documentation
tags?  if so it should be done in some kind of a framework so as not to
lose all the advantages of a standard.  A good approach might be that you
are allowed to extend a standard schema, in some fashion.  This could be
the equivalent of adding custom tags in JavaDoc.  A related issue is should
there be a framework for creating your own SchemaDoc processors, perhaps
similar to Doclets in JavaDoc?
4.) What should the content model of each tag be?  This could range from
'String' to 'Some Type' to 'Any xHTML' to 'Any element from any namespace'.
The simpler the content model, the easier it is for the processor, but the
less that can be expressed.
5.) So far we have only talked about documenting one schema file, but of
course with the use of includes/imports/redefines a bigger problem is
documenting an entire target namespace/multiple namespaces, although this
is more of an issue for version 2.
6.) How do we design the standard so we can create a version 2 of it,
without breaking all the version 1 processors?

-------

[1]
http://lists.w3.org/Archives/Public/www-xml-schema-comments/2000OctDec/0416.html
[2] http://java.sun.com/j2se/1.3/docs/tooldocs/javadoc/index.html
[3] http://www.xmlspy.com/beta35.html
[4] http://uddi.org/schema/uddi_1.xsd


regards,

--
David Bacigalupo
IBM Corporation, Research Division

Received on Friday, 15 December 2000 16:26:05 UTC