Re: DOCBOOK: ClassSynopsis revisited again

[Dmitry Tsitelov <cit@comcon.spb.ru>]

Norman Walsh wrote:
> 
> Looking at ClassSynopsis and considering the more complex case presented
> by C++ (and perhaps other languages), I'm concerned that the existing
> structure is too ambiguous.
> 
...

> Would it be clearer still to put the wrapper around the base
> classname, too?
> 
> <classsynopsis language="cpp">
>   <classparam>
>     <classname>Rectangle_with_data</classname>
>   </classparam>
>   <classparam>
>     <modifier>virtual</modifier><classname>Shape</classname>
>   </classparam>
>   <classparam>
>     <modifier>virtual</modifier><classname>Data_container</classname>
>   </classparam>
> </classsynopsis>
> 
> Probably. Especially if it's a virtual public class or something.
> 
> Unfortunately, classparam is hardly a perfect name, and I
> suppose we'd need to have exceptionparam and implementsparam as
> well. Ack.
> 
> Thoughts?

I think this last variant looks mostly appropriate. But 'classparam'
really isn't perfect
name. May be 'classdeclelem'? Not perfect too. There are some more
problems:

1. Should classparam (or it's substitute) allow any kind of
class/exception/interface   description, or we need wrapper for each
case? 
2. In such structured declaration, wrapper for first classname  should
be different from other wrappers, shouldn't it.
3. May be it will be convenient to allow simple
class/interface/exception references (without modifiers) at the same
level as wrappers?

After all, more general thoughts. I think, current model of class
synopsis is rather weak. Let's keep in mind, that such structure in real
book intended not only to reproduce syntax of class declaration, but to
_document_ class. In FuncSynopsis we have a chance to place some remarks
about function  immediately after syntax representation: In optional
FuncSynopsis info, or after FuncSynopsis element. But current model of
classsynopsis is pure syntax skeleton.

In many published books, we'll see class descriptions much more
complicated than current classsynopsis model:

class Rectangle_with_data: virtual Shape, virtual Data_container
{
// contractors 

   Rectangle_with_data();  // default constructor ...
	...

// Public members
   Object *controller;	   // ...

// drawing control

   bool  some_flag; 	   // controls style of drawing ...
...

}

There are many comments here (in some books they rendered syntactically
as language's comments, in other - just indented comments, hilited by
font or color. Without such info-elements will be hard to understand
declaration of really complicated class. Without some sort of free-form
elements most power of classsynopsis is lost.  

Opinions?

Sincerely,
Dmitry