2011/10/5 Jon Cruz <jon@...18...>:
In order to get a good architectural overview, Doxygen output is a key tool. And if we don't have good Doxygen output, it's hard to see what's going on. It's also hard for newcomers to use it.
This is a non-argument because removing the brief tag does not change the Doxygen output.
So the effort is part of the overall work to have diagrams, charts, maps of where to find what, etc., that will be exactly what newcomers need. And I should also be able to get some templates, guidelines, etc. to help the rest of us gain maximum use with minimal effort.
Also completely unrelated to what you've been actually doing. These things would be valuable, and I'm all for you doing them, but removing forward headers and @brief is at best unnecessary and at worst counterproductive.
For that, you are looking at an 'I want to use some library and not worry' situation. For that purpose, I'd say that <2geom/forward.h> is a bit misleading. A better approach would be to narrow down to some specific types. Or if you really want the convenience of using the library without needing to worry, look for a full-name kind of include-the-whole-world file. Ah, there we go with <2geom/2geom.h> *However* often actually being able to *use* a library will not be safely served via forward includes. To save space in one's header, a few sub-component includes might be more helpful. However, even 2geom's current forward.h appears to be broken.
Writing forward declarations for template types such as std::ostream is non-trivial, and in fact the declarations are often an implementation detail. The same is the case for Geom::Rect. This is why we have <2geom/forward.h> - to allow the library to provide its forward declarations, rather than the user, so that people might use Geom::Rect const & without having to include the entire definition of this type or writing 2Geom implementation details in their headers. <2geom/forward.h> is not broken.
Regards, Krzysztof