OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Subject: Re: DOCBOOK: DocBook 4.0: ClassSynopsis


Christian Leutloff <leutloff@sundancer.oche.de> was heard to say:
 > I like the definition. But I think that the inheritance is
 > missing. There is no way to tell what's the name of the parent
 > class. In C++ these are the class names following the ':' and in Java

Norman Walsh writes:
 > I had imagined that it would be done with multiple classnames:
 > 
 > So the Java class:
 > 
 >   public class foo extends bar implements baz, moo throws x, y
 > 
 > is documented as:
 > 
 > <classsynopsis language="java">
 > <classname>foo</classname>
 > <classname>bar</classname>

  I think the confusion is here.  It's not clear from the DTD that the 
first one is the class identication and the others are base classes
and interfaces that it conforms to.  It's also valid, accoring to the
DTD, to say:

<classsynopsis language="java">
<exceptionname>somename</exceptionname>
...

  Which doesn't make sense (unless your language distinguishes
exceptions from classes; Java only makes requirements on the
inheritance chain).  I also understand that C++ allows exceptions to
be things other than class instances; "int" for example.  But I
suppose ExceptionName doesn't really say it's a class.
  Perhaps the base class(es) and interfaces need to be set up in a
container, with possibly a different container for allowed exceptions?
I don't like getting heavy with markup like this, though.  ;(  Perhaps 
the name of "this" class/interface/exception should be an attribute,
with another attribute that allows specifying which it is (or select
by attribute name); "class" could be the default type for a
ClassSynopsis.

<classsynopsis language="java" type="class" name="foo">
  <inherits>
    <classname>bar</classname>
    <interfacename>baz</interfacename>
    <interfacename>moo</interfacename>
    </inherits>
  <raises>
    <exceptionname>x</exceptionname>
    <exceptionname>y</exceptionname>
    </raises>

  I'm not exactly sure I like this much better, but it takes care of
the potential for ambiguity (for authoring, not processing).

  -Fred

--
Fred L. Drake, Jr.	  <fdrake at acm.org>
Corporation for National Research Initiatives



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]


Powered by eList eXpress LLC