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=-0.9 required=5.0 tests=BAYES_00,FORGED_GMAIL_RCVD, FREEMAIL_FROM autolearn=no autolearn_force=no version=3.4.4 X-Google-Thread: a07f3367d7,887292c91e10d3fd X-Google-Attributes: gida07f3367d7,public,usenet X-Google-NewGroupId: yes X-Google-Language: ENGLISH,ASCII-7-bit Path: g2news2.google.com!news1.google.com!Xl.tags.giganews.com!border1.nntp.dca.giganews.com!nntp.giganews.com!local2.nntp.dca.giganews.com!news.giganews.com.POSTED!not-for-mail NNTP-Posting-Date: Mon, 15 Nov 2010 17:33:33 -0600 Date: Mon, 15 Nov 2010 18:33:19 -0500 From: "Peter C. Chapin" User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.2.12) Gecko/20101027 Lightning/1.0b2 Thunderbird/3.1.6 MIME-Version: 1.0 Newsgroups: comp.lang.ada Subject: Re: Ada documentation tools. References: <45458390-1074-4299-8faf-624bfda6db51@p7g2000prb.googlegroups.com> In-Reply-To: <45458390-1074-4299-8faf-624bfda6db51@p7g2000prb.googlegroups.com> Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 7bit Message-ID: X-Usenet-Provider: http://www.giganews.com X-Trace: sv3-wBPAMJKYqrg/JBZio3HQPkhXiHF14tinrU+Zh6b5bgFFBs5nbiIhrCY1ZignRWENARxIm/9y5Epi+Qz!nqV5tDo9BtrVnzMtPnJuSPFbraIgmYWhSqqy8hdq705wHwdBxh0+4NYyAUCTgk4= X-Complaints-To: abuse@giganews.com X-DMCA-Notifications: http://www.giganews.com/info/dmca.html X-Abuse-and-DMCA-Info: Please be sure to forward a copy of ALL headers X-Abuse-and-DMCA-Info: Otherwise we will be unable to process your complaint properly X-Postfilter: 1.3.40 X-Original-Bytes: 3287 Xref: g2news2.google.com comp.lang.ada:16488 Date: 2010-11-15T18:33:19-05:00 List-Id: On 2010-11-15 07:38, AdaMagica wrote: > Cross-referencing can best be done via the internal program > representation (ASIS e.g.). Why is a browser to be preferred to an IDE > like GPS? It works better on web pages. Documentation in HTML format can be presented on the web for reference or whatever. It could probably also be converted into, for example, CHM format (not sure... haven't actually tried it). Doxygen can extract information from the source (not just comments, but also semantic information from the code itself) and format it as RTF or even LaTeX. There are situations where that is nice. Actually another advantage of using such tools is that it "forces" developers to use a standardized commenting style. For example if I have to use a @param tag, or something similar, to introduce the documentation for a parameter then I know that everyone on the project will be introducing parameter documentation the same way. That's a nice thing too. Comments are free formatted, which can be good at times, but there are also times when I'd like to impose structure on them. Speaking of Doxygen... one thing that I rather like about it is that it allows you to include comments on either the declaration or the definition of a function. The Ada tools I've seen so far believe that all "documentation" comments should appear in the specification. I agree that is logically where they should go but from a maintenance point of view it can be nice to have the documentation for a subprogram right where one spends time editing that subprogram. I understand this invites confusion between documentation for users vs documentation for implementers. Still, it's a nice option to have when used with caution. > Would you try to > browse through a HOOD design or UML model created with some tool with > a browser instead of a dedicated tool? I could imagine wanting to do that, yes. Peter