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.9 required=5.0 tests=BAYES_00 autolearn=unavailable autolearn_force=no version=3.4.4 Path: eternal-september.org!reader01.eternal-september.org!feeder.eternal-september.org!news.swapon.de!fu-berlin.de!uni-berlin.de!individual.net!not-for-mail From: Niklas Holsti Newsgroups: comp.lang.ada Subject: Re: Why .ads as well as .adb? Date: Mon, 10 Jun 2019 00:46:57 +0300 Organization: Tidorum Ltd Message-ID: References: <28facad3-c55f-4ef2-8ef8-004925b7d1f1@googlegroups.com> <87woi0xtwm.fsf@nightsong.com> <4a0438de-1f1d-4469-aae4-908854d378ea@googlegroups.com> <47d02bdc-6b50-43aa-bc5d-bb5b6225f5bd@googlegroups.com> <455333f0-ede4-4833-900a-240a499395ac@googlegroups.com> <875zphvufc.fsf@nightsong.com> <87y32bvbeo.fsf@nightsong.com> <561c766c-4f9c-432c-be9b-822dd9c3c8ba@googlegroups.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit X-Trace: individual.net CZseq+c3oQfMYCk1ri2HxgNe9xicJZIQ0J1mA7k24jW5TzO7v3 Cancel-Lock: sha1:axUpwu+J0Nidp2s9UMU30wfkfQU= User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 In-Reply-To: <561c766c-4f9c-432c-be9b-822dd9c3c8ba@googlegroups.com> Xref: reader01.eternal-september.org comp.lang.ada:56590 Date: 2019-06-10T00:46:57+03:00 List-Id: [ Apologies for duplication: I "sent" this post too early by mistake. ] On 19-06-09 23:35 , John Perry wrote: > ... > > (2) I've read some very good arguments made in favor of separate > specification files, but I don't understand why the conversation > keeps coming around to "the specification file provides convenient > documentation," or even, "if I want to see the specification from the > implementation, I have to run a tool every time I want to see it, and > that can be inconvenient." Those aren't just weak arguments; they're > plainly false. I disagree on the first part: specification files do provide convenient documentation. Of course, "convenient" may be subjective, but I feel sure that a file containing only the specification is more convenient than a file that interleaves specification and implementation, which is what this thread is about. > When I want to know how Ada.Text_IO works, I don't look up the > specification file. I do, about half the time (the rest of the time I look it up in the RM). > I don't even know where to find Ada.Text_IO on my > system. Your IDE (GPS) knows. And its not hard to find, either, once you figure out its file-name (with gnatkr). > ... it's far more > convenient to visit [1], which has a hyperlink to Ada.Text_IO, as > well as lots of other things. Sure the RM is often convenient, but it shows only the standard packages. Most of the packages in a non-trivial application will be application-specific. > I imagine that [1] was generated by some software tool. AIUI it was generated, but not from an Ada spec (.ads) file. > Similar tools > exist for other languages. Take a look at [2] to see what a nice job > they can do -- a LOT nicer than [1]. Matter of opinion. > If I click on > BINARY_SEARCH_TREE, not only do I get the specification for > BINARY_SEARCH_TREE a la [1], but I also get links to related > specifications, such as COMPARABLE, TREE_ITERATION_CURSOR, and so > forth. This is much, _much_ more helpful than the specification file > by itself. A good IDE will give you the same links from the specification file. > Some have suggested that the markup required to do this can make the > source file unreadable. The markup makes the file less readable, IMO, but "unreadable" would be too strong a claim. No markup is really required for getting nice views of the descriptions and cross-links between declarations -- it is enough to follow some simple conventions for systematically locating descriptions (comments) close to the declarations they describe. > Doxygen and javadoc markup aren't especially painful to read, > either, and they do much the same thing. I find them a little painful, though, and it seems that formatting conventions can produce much the same results without markup. > Moreover, there's no need to invoke such a tool every time you want > to see the specification, and thus no inconvenience at all. While a program is being built, the specs of that program's specific packages change often, unlike the spec of standard packages like Text_IO. > You > generate the specification / documentation once and it ends up in a > file that you can distribute just as easily as an .ads. Oh yes, the Doxygen-generated "documentation". Typically it is as useless as the "User Manuals" for GUIs that just show screen-shots of various dialogs and explain things like "to frobnicate the lesneric, press the button -- without any coherent description of "frobnication" or "lesnerics". Taking your reference [2] as an example, most high-level "descriptions" in it are one-liners, as usual in such "documentation". The reference is a little better than usual as it actually gives two or three (short) lines of description for many operations (although shown in a tiny, low-contrast font -- OK, I can magnify...) I could point to some examples of the "frobicate/lesneric" problem in that example, that is, of concepts that are used in the descriptions but nowhere described themselves, but enough said. > The only time > one has to invoke Doxygen, javadoc, etc. is if the exported objects > change. Which is often, when the program is being built. But of course this can be automated -- it is IMO _not_ the main problem with Doxygen-type documentation, and this is anyway not relevant to the subject of this thread: why Ada separates specifications from implementations. > [1] http://www.ada-auth.org/standards/12rm/html/RM-TOC.html > [2] https://www.eiffel.org/files/doc/static/19.05/libraries/base/index.html -- Niklas Holsti Tidorum Ltd niklas holsti tidorum fi . @ .