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 X-Received: by 2002:a5d:8c97:: with SMTP id g23mr13740907ion.250.1560119847184; Sun, 09 Jun 2019 15:37:27 -0700 (PDT) X-Received: by 2002:a9d:7741:: with SMTP id t1mr19213332otl.178.1560119846885; Sun, 09 Jun 2019 15:37:26 -0700 (PDT) Path: eternal-september.org!reader01.eternal-september.org!feeder.eternal-september.org!news.dns-netz.com!news.freedyn.net!newsfeed.xs4all.nl!newsfeed7.news.xs4all.nl!85.12.16.68.MISMATCH!peer01.ams1!peer.ams1.xlned.com!news.xlned.com!peer01.am4!peer.am4.highwinds-media.com!peer02.iad!feed-me.highwinds-media.com!news.highwinds-media.com!s188no637130itb.0!news-out.google.com!l135ni707itc.0!nntp.google.com!s188no637129itb.0!postnews.google.com!glegroupsg2000goo.googlegroups.com!not-for-mail Newsgroups: comp.lang.ada Date: Sun, 9 Jun 2019 15:37:26 -0700 (PDT) In-Reply-To: Complaints-To: groups-abuse@google.com Injection-Info: glegroupsg2000goo.googlegroups.com; posting-host=2601:3c3:401:f550:3d6d:6db5:dda4:ab9b; posting-account=JSxOkAoAAADa00TJoz2WZ_46XrZCdXeS NNTP-Posting-Host: 2601:3c3:401:f550:3d6d:6db5:dda4:ab9b 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> User-Agent: G2/1.0 MIME-Version: 1.0 Message-ID: Subject: Re: Why .ads as well as .adb? From: John Perry Injection-Date: Sun, 09 Jun 2019 22:37:27 +0000 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable X-Received-Bytes: 7662 X-Received-Body-CRC: 2167405967 Xref: reader01.eternal-september.org comp.lang.ada:56592 Date: 2019-06-09T15:37:26-07:00 List-Id: 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. >=20 > Your IDE (GPS) knows. And its not hard to find, either, once you figure= =20 > 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 t= ool for it, and in this case you really *do* have to use the special tool e= very 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 & AdaCor= e has been really nice with some help (I'm an academic), so I should probab= ly 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 eas= iest 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. >=20 > The markup makes the file less readable, IMO. No markup is really=20 > required for getting nice views and cross-links -- it is enough to=20 > follow some simple conventions for locating descriptions (comments)=20 > close to the declarations they describe. I agree with the second part, but since all the markup I've seen for Doxyge= n 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 dissen= t. :-) > > Moreover, there's no need to invoke such a tool every time you want > > to see the specification, and thus no inconvenience at all. >=20 > While a program is being built, the specs of that program's specific=20 > packages change often, unlike the spec of standard packages like Text_IO. Fair enough, but a lot of the conversation previously had revolved around d= ifferent teams in different locations, and my impression from the conversat= ion 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" fo= r GUIs that just show screen-shots of various dialogs and explain things li= ke "to frobnicate the lesneric, press the button = -- without any coherent description of "frobnication" or "lesnerics".=20 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) terri= bly written documentation, (2) non-working sample code, and (3) a Google de= veloper's Google+ help page that featured soft porn (I swear I am not makin= g 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 us= e 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 sof= tware development outfit, etc. We're supposed to be talking about a languag= e and/or documentation issue. If you want to argue that Ada's approach to separating spec and implementat= ion 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 convincin= g. I think it much more likely that if Ada's users are generally more caref= ul with documentation, then that has a lot to do with their target applicat= ions: if an Android app crashes, who cares? but if a Boeing falls out of th= e sky, that's a problem. As far as I can tell, this has nothing at all to do with having two files v= ersus 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 sub= ject of this thread: why Ada separates specifications from implementations. Right. My quarrel, which is really more of an irritation, is with those who= se arguments suggest they think it's impossible to generate specification /= documentation from an implementation file, and that seems to keep coming u= p, 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.