Re: Why .ads as well as .adb?

[John Perry <john.perry@usm.edu>]

Hi Niklas

Let me preface my reply by saying that I think we mostly agree.

On Sunday, June 9, 2019 at 4:15:37 PM UTC-5, Niklas Holsti wrote:
> > 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).

Sure, but such an IDE has to be Ada-ready, and in any case turns one of the arguments I was complaining about on its head: you have to use a special tool for it, and in this case you really *do* have to use the special tool every time you want to look something up. The Eiffel documentation I pointed to, like the ADA RM, doesn't require anything more than a web browser.

You refer to GPS. GPS does not come with FSF gnat, at least not on my Linux distribution (Fedora), not as far as I know. For the first couple of years I toyed with Ada, that's what I had. Also, I never heard of gnatkr before reading this, and it doesn't seem to have a man file on any of my systems. I do however appreciate learning this!

[Now that I'm getting more serious, I've downloaded the CE edition & AdaCore has been really nice with some help (I'm an academic), so I should probably acknowledge that.]

> AIUI it was generated, but not from an Ada spec (.ads) file.

I would like to know how that was generated. I figured the spec was the easiest way to do it. A lot of the documentation in the RM is really thorough -- a bit intimidating in its thoroughness, in fact.

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

I agree with the second part, but since all the markup I've seen for Doxygen and javadoc appear in comments, I don't really understand the first. It's an opinion, so I can't really complain, but I do wish to express my dissent. :-)

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

Fair enough, but a lot of the conversation previously had revolved around different teams in different locations, and my impression from the conversation was that those specs were fairly stable. That was the context I had in mind, but I agree with what you say, if only from painful experience.

> Typically [Doxygen-generated spec] 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 <Frobnicate the Lesneric> button -- without any coherent description of "frobnication" or "lesnerics". 

Of course. I think I deleted from my earlier message a brief rant on how I once tried to figure out an Android service and ended up fighting (1) terribly written documentation, (2) non-working sample code, and (3) a Google developer's Google+ help page that featured soft porn (I swear I am not making any of this up). In the end I had spent 8 hours trying to figure out why my code wouldn't work, simple because Google's documentation told you to use version X, while the sample code used version Y, and for whatever reason I actually had to use version Z. (The fact that the sample code didn't work was actually part of what clued me in to the problem.)

So I am absolutely nodding as I read what you're saying there. But, that's more a problem with the writer of the documentation, the culture of the software development outfit, etc. We're supposed to be talking about a language and/or documentation issue.

If you want to argue that Ada's approach to separating spec and implementation forces the programmer to write better documentation than you'd get from Doxygen, javadoc, etc., you're welcome to make that argument. Some people have hinted in that direction, but I haven't seen anything really convincing. I think it much more likely that if Ada's users are generally more careful with documentation, then that has a lot to do with their target applications: if an Android app crashes, who cares? but if a Boeing falls out of the sky, that's a problem.

As far as I can tell, this has nothing at all to do with having two files versus having one file, and that's my point. So we seem to be in agreement, since as you point out:

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

Right. My quarrel, which is really more of an irritation, is with those whose arguments suggest they think it's impossible to generate specification / documentation from an implementation file, and that seems to keep coming up, so I just wanted to put a quick word in about it. That's all. It has no bearing at all with the great answers provided by others, and for which I'm grateful.