From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.3 required=5.0 tests=BAYES_00,INVALID_MSGID autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,3334f982144a667d X-Google-Attributes: gid103376,public From: dewar@merv.cs.nyu.edu (Robert Dewar) Subject: Re: javadoc => adadoc? Date: 1998/08/04 Message-ID: #1/1 X-Deja-AN: 377746049 References: <6ptlbe$k3$1@nnrp1.dejanews.com> <6pvslq$poo@drn.newsguy.com> <6q4k5q$10uo$1@mdnews.btv.ibm.com> <35C5DAC4.F68DA421@earthling.net> X-Complaints-To: usenet@news.nyu.edu X-Trace: news.nyu.edu 902212547 28917 (None) 128.122.140.58 Organization: New York University Newsgroups: comp.lang.ada Date: 1998-08-04T00:00:00+00:00 List-Id: Norm said <<> The true benefit of javadoc is the automated generation of hypertext > documentation that can be viewed with a browser. Indices by package, by > class, and by method name, as well as links to related pages (e.g. from the >> Very nice, but not for a moment would I describe this as documentation! The danger of such tools is precisely that it leads sloppy coders to think that they don't need to document their code, because some automatic tool can do it for them. Documentation is all about providing information that is NOT readily derivable from the code, by either a human or by a simple minded tool. For example, one critical aspect of documentation is to say what you did NOT do and why you did NOT do it!