RE: DocBook function synopsis

["Frank A. Christoph" <christo@xxxxxxxxxxxxxxxxxx>]

>> I added three attributes to FuncDef in the declaration subset, "Class"
which
>> indicates what class the function is a member of (I'm not using it, but
it
>> seems potentially useful); "Dispatch" which would be "pure" for pure
virtual
>> functions, "virtual" for regular dynamically dispatched functions, and
>> "static" for statically dispatched functions; and finally "Const" which
is
>> "const" for functions that don't modify the state, or "mutable" for those
>> that do.
>>
>> <!-- customizations -->
>> <!ENTITY % local.funcdef.attrib "
>>   Class   CDATA #IMPLIED
>>   Dispatch (pure|virtual|static) static
>>   Const   (const|mutable) mutable" >
>
>Not to go into too much C++ detail for the DSSSL list, I'd suggest
youchange the default for Displatch to #IMPLIED. "static" has its own
>meaning which has nothing to do with the default dispatch method
>used for unqualified method declarations (which are sensitive to
>the context). An implied value would mean "unknown, let the compiler
>figure it out," which is probably a more accurate representation of
>real life.

I agree that "static" is misleading in this case; at the time, I couldn't
think of a better word to describe the opposite of "virtual."  Actually, it
later occurred to me to use the a declaration like the following instead

<!ENTITY % local.funcdef.attrib "
  Class CDATA #IMPLIED
  Abstract (abstract|concrete) concrete     -- pure or not --
  Dispatch (dynamic|static) static          -- virtual or not --
  Effect (functional|imperative) imperative -- const or not --">

which I think is clearer, since it avoids the eccentricities of C++
terminology.  Anyway, the specific names are still not decided.

I'm not so happy using #IMPLIED.  I think #IMPLIED should be avoided when
possible since it lets different SGML applications choose different
defaults.  When you say that the default dispatch method is sensitive to
context, are you referring to the fact that you can omit the "virtual"
keyword when you redefine a virtual member function in a derived class?  I
don't think that is an argument for making the documentation of the dispatch
method context-sensitive: isn't it more sensible to omit mentioning
inherited methods, period?  One could argue that you should mention it again
when you redefine it, like C++ forces you to, but I think that is an
implementation concern and here I'm concentrating on just documenting the
interface(s).

>Also, what about "inline"?

This is definitely an implementation concern.  You don't need to know
whether a method is inlined or not to be able to use it correctly.

>If this is all you need to know, that's great. I wonder though, because
>there is so much Stuff (with a capital S) in C++ syntax that you could
>easily become swamped trying to handle the gOofY rules.

Again, I have no intention of supporting every little nook and cranny of C++
syntax.  But I'm looking right now at some possibilities for a generic class
synopsis that would be useful for documenting C++, Java and IDL interfaces
(like an poster suggested the other day).

--FC



 DSSSList info and archive:  http://www.mulberrytech.com/dsssl/dssslist