RE: [Doxygen-users] Documenting abstract base classes

[Jan R. <ja...@mo...>]

Hello Evil,
	Yes I know what you mean. The answer depends on whom you documenting
for. If you are documenting for the users/clients of the classes then I
would say document the "behavior" of each pure virtual function in the
abstract base class. That is all the clients should worry about. Clients
should not need to read any docs for the derived (implementation) classes,
they just need to know that those concrete classes exist.
	On the other hand if you are documenting for the maintainer of the
code then the long description for each implementation member function could
discuss the method and quirks involved in carrying out that particular
implementation. I think you can use the \internal keyword for these types of
comments.  This will allow you to generate a complete set of docs for
maintainers and a more cleansed set for users/clients.  Either
way you don;t double document the member functions in the derived class.
	One feature that I would find nice is some way to get a member
function listed without requiring any comment text.  For example

class File
{
  virtual void Open(const char* name,bool read_only) const; //!<
};

This declaration is largely self documenting, putting in a comment like 
//<! Opens a file.

is redundant.  BUT Doxygen will ignore this function as typed above, I have
to put at least one character after //!< to get the function listed. And a
line is wasted in the generated docs.

Regards
Jan
	


> -----Original Message-----
> From: Evil Kosh [mailto:evi...@ya...]
> Sent: Thursday, March 07, 2002 10:45 AM
> To: Doxygen Mailing list
> Subject: [Doxygen-users] Documenting abstract base classes
> 
> 
> Hi guys, busy tonight huh =]
> 
> okay, I was wondering, if I have an abstract base class and a 
> derived type, 
> the methods in the base class and derived class do the same 
> job, but where 
> to put the documentation saying what the method does.  What I 
> mean, is 
> you've got the abstract base class, do you put the 
> documentation saying 
> what each method does in there with the class, or do you 
> leave all the 
> documentation for each implementation you do of that base 
> class?  Since if 
> you have a base class and derived class, if you document 
> both, you'll be 
> repeating documentation wont you, for each class, so it seems kinda 
> silly.  Especially when you read the documentation back to 
> yourself, you 
> read the definition, it says "Opens a File", then nothing 
> else, then you 
> read the implemenation, it says "Opens a File" and then goes 
> on to say what 
> the actions of the method are, what it does, etc etc.
> 
> Does anyone know what I mean? if they do, what do you do in 
> this situation? 
> do you only document the abstract base class or the derived, 
> or do you 
> document both?
> 
> thanks again!
> 
> kosh 
> 
> 
> _________________________________________________________
> Do You Yahoo!?
> Get your free @yahoo.com address at http://mail.yahoo.com
> 
> 
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users
>