RE: DocBook function synopsis

Subject: RE: DocBook function synopsis
From: "Frank A. Christoph" <christo@xxxxxxxxxxxxxxxxxx>
Date: Fri, 10 Jul 1998 11:52:16 +0900
>> I added three attributes to FuncDef in the declaration subset, "Class"
>> indicates what class the function is a member of (I'm not using it, but
>> seems potentially useful); "Dispatch" which would be "pure" for pure
>> functions, "virtual" for regular dynamically dispatched functions, and
>> "static" for statically dispatched functions; and finally "Const" which
>> "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 "
  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

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


 DSSSList info and archive:

Current Thread
  • RE: DocBook function synopsis, (continued)
    • Frank A. Christoph - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id XAA11708Wed, 8 Jul 1998 23:33:04 -0400 (EDT)
      • Lionel Mallet - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id DAA16760Thu, 9 Jul 1998 03:02:38 -0400 (EDT)
      • Mitch C. Amiano - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id RAA02041Thu, 9 Jul 1998 17:03:33 -0400 (EDT)
    • Frank A. Christoph - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id DAA20422Thu, 9 Jul 1998 03:45:12 -0400 (EDT)
    • Frank A. Christoph - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id WAA27256Thu, 9 Jul 1998 22:45:28 -0400 (EDT) <=
      • Mitch C. Amiano - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id KAA13750Fri, 10 Jul 1998 10:23:10 -0400 (EDT)
        • Graydon Hoare - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id LAA18381Fri, 10 Jul 1998 11:53:57 -0400 (EDT)
        • Mitch C. Amiano - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id PAA29953Fri, 10 Jul 1998 15:18:28 -0400 (EDT)
      • Mitch C. Amiano - from mail1.ability.netby (8.8.5/8.6.12) with ESMTP id KAA14489Fri, 10 Jul 1998 10:58:42 -0400 (EDT)