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. Just my two cents, Igor On Tue, 2010-06-08 at 12:59 -0400, Tim Vandermeersch wrote: > Hi, > > Andrew has raised some important issues with outdated docs etc. I > think we should turn all wiki pages into in-source documentation > (using doxygen for example) that is updated nightly. The current wiki > is just not suited for maintainability IMHO, there is no real overview > of files. We can't grep through it. It can also be a set of test > files, as long as it is easier to maintain. Do we really benefit from > the wiki? I mean: Are there users contributing to the wiki who > wouldn't if we moved it to svn/git. > > I've but serious effort in documenting my changes to the > stereochemistry but this can only be seen by generating the developer > docs. > > Tim > > ------------------------------------------------------------------------------ > 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 > > 000278d9-0010From cja...@emolecules.com Tue Jun 8 13:23:59 2010 > Received: from nihrelayxway2.hub.nih.gov (128.231.90.107) by > NIHHT02.nih.gov (156.40.71.21) with Microsoft SMTP Server id 8.2.254.0; > Tue, 8 Jun 2010 13:23:59 -0400 > Received: from helix.nih.gov (HELO helixmail.cit.nih.gov) ([128.231.2.3]) > by nihrelayxway2.hub.nih.gov with ESMTP; 08 Jun 2010 13:23:58 -0400 > Received: by helixmail.cit.nih.gov (Postfix) id 9ED881007C; Tue, 8 Jun > 2010 13:23:58 -0400 (EDT) > Received: from nihsmtpxway2.hub.nih.gov (unknown [128.231.90.104]) by > helixmail.cit.nih.gov (Postfix) with ESMTP id 938251007B for > <ig...@helix.nih.gov>; Tue, 8 Jun 2010 13:23:58 -0400 (EDT) > Received: from lists.sourceforge.net ([216.34.181.88]) by > nihsmtpxway2.hub.nih.gov with ESMTP; 08 Jun 2010 13:23:58 -0400 > Received: from localhost ([127.0.0.1] > helo=sfs-ml-1.v29.ch3.sourceforge.com) by sfs-ml-1.v29.ch3.sourceforge.com > with esmtp (Exim 4.69) (envelope-from > <openbabel-devel-boun...@lists.sourceforge.net>) id 1OM2Wc-00029A-Nk; > Tue, > 08 Jun 2010 17:23:42 +0000 > Received: from sfi-mx-1.v28.ch3.sourceforge.com ([172.29.28.121] > helo=mx.sourceforge.net) by sfs-ml-1.v29.ch3.sourceforge.com with esmtp > (Exim 4.69) (envelope-from <cja...@emolecules.com>) id 1OM2Wb-000294-S4 > for > openbabel-devel@lists.sourceforge.net; Tue, 08 Jun 2010 17:23:41 +0000 > Received: from mail-pv0-f175.google.com ([74.125.83.175]) by > sfi-mx-1.v28.ch3.sourceforge.com with esmtp (Exim 4.69) id > 1OM2Wa-0007ii-Jx > for openbabel-devel@lists.sourceforge.net; Tue, 08 Jun 2010 17:23:41 +0000 > Received: by pvc21 with SMTP id 21so368687pvc.34 for > <openbabel-devel@lists.sourceforge.net>; Tue, 08 Jun 2010 10:23:34 -0700 > (PDT) > Received: by 10.142.1.2 with SMTP id 2mr196546wfa.73.1276017814669; Tue, 08 > Jun 2010 10:23:34 -0700 (PDT) > Received: from Craig-Jamess-MacBook-Pro.local > (wsip-70-167-124-126.sd.sd.cox.net [70.167.124.126]) by mx.google.com with > ESMTPS id w39sm2080267wfh.15.2010.06.08.10.23.32 (version=SSLv3 > cipher=RC4-MD5); Tue, 08 Jun 2010 10:23:33 -0700 (PDT) > From: "Craig A. James" <cja...@emolecules.com> > To: "openbabel-devel@lists.sourceforge.net" > <openbabel-devel@lists.sourceforge.net> > Date: Tue, 8 Jun 2010 13:23:31 -0400 > Subject: Re: [OpenBabel-Devel] Documentation (Was: State of OB features) > Thread-Topic: [OpenBabel-Devel] Documentation (Was: State of OB features) > Thread-Index: AcsHL2GaGQgiNdpiTc2NhY1QSvl4xg== > Message-ID: <4c0e7c93.2020...@emolecules.com> > References: <aanlktimcnuqqrnypj1rc3fzgthu0idfvei54kx35s...@mail.gmail.com> > List-Help: > <mailto:openbabel-devel-requ...@lists.sourceforge.net?subject=help> > List-Subscribe: > <https://lists.sourceforge.net/lists/listinfo/openbabel-devel>, > <mailto:openbabel-devel-requ...@lists.sourceforge.net?subject=subscribe> > List-Unsubscribe: > <https://lists.sourceforge.net/lists/listinfo/openbabel-devel>, > <mailto:openbabel-devel-requ...@lists.sourceforge.net?subject=unsubscribe> > In-Reply-To: <aanlktimcnuqqrnypj1rc3fzgthu0idfvei54kx35s...@mail.gmail.com> > Accept-Language: en-US > Content-Language: en-US > X-MS-Exchange-Organization-AuthAs: Internal > X-MS-Exchange-Organization-AuthMechanism: 10 > X-MS-Exchange-Organization-AuthSource: NIHHT02.nih.gov > X-MS-Has-Attach: > X-Auto-Response-Suppress: All > X-MS-TNEF-Correlator: > x-sbrs: 4.4 > x-ironportlistener: NON_CES-Inbound > x-spam-score: 0.0 (/) > user-agent: Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; > rv:1.9.1.9) Gecko/20100317 Thunderbird/3.0.4 > x-ironport-anti-spam-result: > Ai4BAAcaDkzYIrVYkGdsb2JhbACSLYwLCBUBAQEBCQkMBxEFHacamDOFFgSDRyCDGw > x-ironport-anti-spam-filtered: true > errors-to: openbabel-devel-boun...@lists.sourceforge.net > x-ironport-av: E=Sophos;i="4.53,385,1272859200"; d="scan'208";a="212928094" > list-archive: > <http://sourceforge.net/mailarchive/forum.php?forum_name=openbabel-devel> > list-post: <mailto:openbabel-devel@lists.sourceforge.net> > x-mailman-version: 2.1.9 > list-id: <openbabel-devel.lists.sourceforge.net> > x-beenthere: openbabel-devel@lists.sourceforge.net > x-spam-report: Spam Filtering performed by mx.sourceforge.net. See > http://spamassassin.org/tag/ for more details. _SUMMARY_ > delivered-to: ig...@helix.nih.gov > x-acl-warn: > Content-Type: text/plain; charset="us-ascii" > Content-Transfer-Encoding: quoted-printable > MIME-Version: 1.0 > X-Evolution-Source: pop://filipp...@mail.nih.gov/ > X-Evolution: 000278db-0000 > > On 6/8/10 9:59 AM, Tim Vandermeersch wrote: > > Andrew has raised some important issues with outdated docs etc. I > > think we should turn all wiki pages into in-source documentation > > (using doxygen for example) that is updated nightly. The current wiki > > is just not suited for maintainability IMHO, there is no real overview > > of files. We can't grep through it. It can also be a set of test > > files, as long as it is easier to maintain. Do we really benefit from > > the wiki? I mean: Are there users contributing to the wiki who > > wouldn't if we moved it to svn/git. > > I've been an advocate of in-line documentation for decades. I've managed a > number of groups of programmers over several decades, ranging from small to > dozens, working on C, C++, Lisp, Perl, Java, JavaScript, assembly language, > even Algol and Pascal. In all that time, I have never once seen a project > where out-of-line documentation was kept up to date. > > On the other hand, the projects I worked on and managed that used in-line > documentation almost always kept it up to date. It's just natural. > > Everyone has good intentions, everyone promises to keep the docs up to date, > but it just doesn't happen. I've even had projects where developers weren't > allowed to change code until after they'd updated the docs, but it didn't > work. > > I'm with Tim on this one. > > Craig > > ------------------------------------------------------------------------------ > 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 ------------------------------------------------------------------------------ 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
