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:15:36 +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 U9qy2kfgPHIDY3SMdoDqbA5DmfThaIMzCJfuAdhI634h3qyKlF Cancel-Lock: sha1:m1HazdNl6vSJg68yCpORHes/KRA= 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:56588 Date: 2019-06-10T00:15:36+03:00 List-Id: 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. > > 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. > Some have suggested that the markup required to do this can make the > source file unreadable. The markup makes the file less readable, IMO. No markup is really required for getting nice views and cross-links -- it is enough to follow some simple conventions for 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. > 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. The only time > one has to invoke Doxygen, javadoc, etc. is if the exported objects > change. > > The downside is that you *have* to remember to update the > documentation -- something I usually do remember, but not always. > That's what made me think that Ada's approach does offer an advantage > here (see above). > > [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 . @ .