[Debtags-devel] Hello, and a few improved tag descriptions

Benjamin Mesing bensmail@gmx.net
Fri, 10 Jun 2005 10:21:47 +0200


> > > And in templates it's almost impossible to use them, as one of the
> > > template parameters could be a class which throws exceptions in copy
> > > operators or other places unexpected by the template.
> > Perhaps you should replace them by doxygens @throws comment instead.
> Interesting idea.  However I imagine that doxygen doesn't check for
> "throw SomeClass" statements in the code, so maintaining those clauses
> over code refactoring would be a huge headache.
Do you agree that it is a good idea to tell the user(developer) which
exceptions are thrown if something  goes wrong?
      * throws FileNotFoundException if the handed file was not found
      * throws FileNotAccessibleException if the file was not accessible
        (most likely do to missing permissions or file locks)

I think this is important. I don't want to dig down into your code to
know which exceptions might be thrown, and I don't like to catch
(std::exception) either, which btw. does not ensure you to catch all the
exceptions in C++. So you need a way to document the exceptions that
might be thrown. You can use @thrown for this purpose or simply list
them in an HTML list or whatever you like.
The advantage of documentation over exception specification is, that the
location and the type of the exception does not get obscured if you
forget to document them. Most exceptions will probably happen to be bugs
in the usage of your library and interest the developer instead of the
end user (whom it will care very little if a std::unexpected exception
crashed his program or a more meaningfull one).
So please try to document the exception, even if there might miss some
of them! 

Greetings Ben