Re: Why .ads as well as .adb?

[Niklas Holsti <niklas.holsti@tidorum.invalid>]

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
       .      @       .