Fabien Costantini wrote: > Ok, If we agree that we put the the api comments in the sources cxx files, > (which seems to be the best consensus according to feedback), > I'm ready to go now (and armed with a cool tool i made last night) !
Sorry, but I don't think that this "seems to be the best consensus". At least not, if you suggest to put all doxygen comments in the source files. I would really prefer to see the documentation at the same places, where the code is, as written in the CMP. I can understand your point that changing the documentation (only) in a header file would lead to recompilation of maybe many files, but OTOH, the documentation should in most cases only need updates, when something changes. And then, it would be best to have the source and documentation at the same places. I can't imagine to document classes and member variables and inline methods in the (cxx) source files, if their only "source code" is in the header files. OTOH, long documentations (comments) in the header files, would also mean much file i/o while compiling and including the headers (at least for the preprocessor). However, looking at fltk 2.0: it's done just this way: almost all doxygen comments are in the .cxx files. I don't know what would be the best - but I think that we should not try to get a fast result at the expense of having more problems later, when the code "lives" and we would find that source code and documentation diverge. Albrecht _______________________________________________ fltk-dev mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk-dev
