On Wed, 9 Jun 2010 01:47:18 +0200 Tim Vandermeersch <tim.vandermeer...@gmail.com> wrote:
> On Tue, Jun 8, 2010 at 11:39 PM, Igor Filippov [Contr] > <filipp...@mail.nih.gov> wrote: > > Don't want to intrude, but for what it's worth I (as a user) > > absolutely hate doxygen produced "documentation". The quotes are > > intentional. Give me a webpage with examples any time, but I've > > seen so many doxygen generated "help" pages which are completely > > unhelpful that were the question put to a vote I would vote "No" > > without reservations. It's not a democracy though, is it? :) > > > > On the other hand it's very often the case that the documentation > > fails to distinguish between planned or desired features from the > > ones that have already been implemented. This is very frustrating > > as well. If it's not in the latest stable release it shouldn't be > > described as available. > > I don't think we should use doxygen but in it's defense: > > This really depends on the quality of the docs. You probably mean the > one line per class/function docs. I agree, they are useless. However, > if you combine them with pages with rich pages (docs, images, > references, ...), doxygen can be used to create good docs. The real > API reference, combined with these pages are essentially what makes > documentation good IMHO. They both play their role. These rich pages > are usually the missing part in bad docs. The docs should be easy to > read gradually increasing the difficulty level, A simple page > describing the various classes in a specific area can do wonders. > > The most important part is the hosting in a repository. This will also > help to keep it in sync with the branches. > > Some examples: > http://openbabel.selfip.org/ob-api/group__stereo.shtml (The openbabel > stereo code) > http://openbabel.selfip.org/jchemhub/docs/index.html (From another > project, far from finished but the general idea is there) > > I see your point though. Having a default doxygen page as the main > portal is not a good idea. > Hi! I also want to advocate Doxygen. It has a lot of useful capabilities like "see also" for related methods and classes, automatic link for method/class names in documentation text, class diagrams generation. Also, it allows to add custom html header and footer for pages, embed custom html fragments into documantation, so it could even serve as "CMS" for website -- Regards, Konstantin ------------------------------------------------------------------------------ ThinkGeek and WIRED's GeekDad team up for the Ultimate GeekDad Father's Day Giveaway. ONE MASSIVE PRIZE to the lucky parental unit. See the prize list and enter to win: http://p.sf.net/sfu/thinkgeek-promo _______________________________________________ OpenBabel-Devel mailing list OpenBabel-Devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/openbabel-devel
