Is the Documentation In a spec File Usually Enough For You ?

Is the Documentation In a spec File Usually Enough For You ?

[patrick]

Hi Everyone

I was just reading through the list of libraries included in C++ boost. We don't have matches for all of this but the libraries that ship with Ada have quite a bit of coverage too and I was surprised that we more or less match up.

The thing is, that the Ada libraries come with almost no documentation/example code at all.

Do you find that just reading through the spec files is enough for you to understand how to use the library in most cases? I was thinking I would try more of them out but I also wonder if I am about to go off on a suicide mission.

-Patrick

Re: Is the Documentation In a spec File Usually Enough For You ?

[Henrik Härkönen]

On Monday, 15 October 2018 03:42:05 UTC+3, pat...@spellingbeewinnars.org  wrote:
> Hi Everyone
> 
> I was just reading through the list of libraries included in C++ boost. We don't have matches for all of this but the libraries that ship with Ada have quite a bit of coverage too and I was surprised that we more or less match up.
> 
> The thing is, that the Ada libraries come with almost no documentation/example code at all.
> 
> Do you find that just reading through the spec files is enough for you to understand how to use the library in most cases? I was thinking I would try more of them out but I also wonder if I am about to go off on a suicide mission.
> 
> -Patrick

My experience of Ada is still very limited, but so far I'd like to say that I like the separate spec files, and for small "interfaces" the might be enough. But I'm also a learn-by-example kind of person, so an example always gives me much more confidence when starting to use some new library. I don't think that seeing just the types and function signatures is always enough to convey the "intent" of that particular interface.

-H

Re: Is the Documentation In a spec File Usually Enough For You ?

[Dmitry A. Kazakov]

On 2018-10-15 02:42, patrick@spellingbeewinnars.org wrote:

> The thing is, that the Ada libraries come with almost no documentation/example code at all.

Some specific libraries in mind?

> Do you find that just reading through the spec files is enough for you to understand how to use the library in most cases? I was thinking I would try more of them out but I also wonder if I am about to go off on a suicide mission.

Usually specifications is all you need.

Tricky stuff must be explained of course, especially things which 
specifications do not cover: exception contracts, behavior under 
tasking, numeric complexity etc.

Frameworks is a different kind of thing, they always require getting 
started, examples etc, regardless the language.

-- 
Regards,
Dmitry A. Kazakov
http://www.dmitry-kazakov.de

Re: Is the Documentation In a spec File Usually Enough For You ?

[Niklas Holsti]

On 18-10-15 03:42 , patrick@spellingbeewinnars.org wrote:
> Hi Everyone
>
> I was just reading through the list of libraries included in C++
> boost. We don't have matches for all of this but the libraries that
> ship with Ada have quite a bit of coverage too and I was surprised
> that we more or less match up.
>
> The thing is, that the Ada libraries come with almost no
> documentation/example code at all.

If you mean the language-defined libraries, such as the standard 
container packages, those are of course documented in the Ada Reference 
Manual, which can be found at http://www.ada-auth.org/arm.html.

The RM description is rather condensed and the number of examples is 
small, but I have found them sufficient.

For more tutorial documentation and more examples one must turn to books 
or other learning materials (http://www.adaic.org/learn/materials/).

-- 
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
       .      @       .

Re: Is the Documentation In a spec File Usually Enough For You ?

[AdaMagica]

If you think of nonlanguage defined libraries, I must say that what I've seen so far is mostly very poorly documented.
It's rarely the case that the pure Ada text in the package specs is enough to understand how a library works and how it is supposed to be used. At least a lot of comments should be included.
In an ideal world, any libraries should be documented in the same detail as all language supplied ones in the RM.
This is almost never the case.
The biggest sin: If you want to use some library and have to look into the bodies to find out how it has to be used and what it does.

Re: Is the Documentation In a spec File Usually Enough For You ?

[patrick]

Thanks Guys

So I just printed all the headers for the Ada.XXX packages and picked one at random. Yes the reference manual covered it, that helps a lot.

I also printed all the Gnat.XXX headers and here are a few just randomly picked:
Gnat.Heap.Sort_G
Gnat.Memory_dump
Gnat.Byte_Swapping

I just picked Gnat.Byte_Swapping and I tried to look for an example. I found the GNAT reference manual that gives a short description but I did not find an example of it in use.

Can I assume that if Adacore included this, it's good software ? but can I also assume that I will need to post to this list and/or read through the spec and body to understand how it works?

Re: Is the Documentation In a spec File Usually Enough For You ?

[Markus Schöpflin]

On 10/15/18 1:25 PM, patrick@spellingbeewinnars.org wrote:

[...]

> I also printed all the Gnat.XXX headers and here are a few just randomly picked:
> Gnat.Heap.Sort_G
> Gnat.Memory_dump
> Gnat.Byte_Swapping
> 
> I just picked Gnat.Byte_Swapping and I tried to look for an example. I found the GNAT reference manual that gives a short description but I did not find an example of it in use.
> 
> Can I assume that if Adacore included this, it's good software ? but can I also assume that I will need to post to this list and/or read through the spec and body to understand how it works?

AdaCore includes extensive documentation in the spec files. So you just need 
to look at the spec files, e.g. for Gnat.Byte_Swapping have a look at 
g-bytswa.ads.

Markus

Re: Is the Documentation In a spec File Usually Enough For You ?

[patrick]

Okay thanks :)

As long as I am SUPPOSED to know how to use the library by using only the spec file, I will give it a try.

Thanks to everyone again

Re: Is the Documentation In a spec File Usually Enough For You ?

[Jeffrey R. Carter]

On 10/15/2018 02:42 AM, patrick@spellingbeewinnars.org wrote:
> 
> The thing is, that the Ada libraries come with almost no documentation/example code at all.

"The Ada libraries" covers a lot of ground. If you're referring to the standard 
library, as others have pointed out, it's well documented in the ARM.

For other libraries, if they can't be used by only reading the specs or by 
documentation similar to that in Annex A, then I question the competence of the 
developer and the correctness of the implementation.

(Now you can look at the pkgs at github.com/jrcarter and question my competence. 
If they can be clearer I'd like to improve them.)

-- 
Jeff Carter
"Insufficient laughter--that's grounds for divorce."
Play It Again, Sam
126

Re: Is the Documentation In a spec File Usually Enough For You ?

[AdaMagica]

Am Montag, 15. Oktober 2018 18:50:23 UTC+2 schrieb Jeffrey R. Carter:
> For other libraries, if they can't be used by only reading the specs or by 
> documentation similar to that in Annex A, then I question the competence of the 
> developer and the correctness of the implementation.

How true!

> (Now you can look at the pkgs at github.com/jrcarter and question my competence. 
> If they can be clearer I'd like to improve them.)

OK. In function Password_Generation.Generate, what are Domain and Master for?
What does Hash_Symbol do?

What does "correctness of the implementation" mean for this package?

Re: Is the Documentation In a spec File Usually Enough For You ?

[Jeffrey R. Carter]

On 10/16/18 11:57 AM, AdaMagica wrote:
> 
> OK. In function Password_Generation.Generate, what are Domain and Master for?
> What does Hash_Symbol do?

Good points. This was extracted from a more monolithic, earlier version of 
Password_Gen, where perhaps these concepts were better explained, and I didn't 
think to clarify them when I pulled them out. I'll try to explain these better.

> What does "correctness of the implementation" mean for this package?

That the function returns the same password for the same inputs, and the 
passwords have all the desirable features for generated passwords:  they appear 
random, contain characters from all the major food groups, and give away nothing 
about the master password.

-- 
Jeff Carter
"Blessed is just about anyone with a vested interest in the status quo."
Monty Python's Life of Brian
73

Re: Is the Documentation In a spec File Usually Enough For You ?

[AdaMagica]

Am Dienstag, 16. Oktober 2018 18:57:51 UTC+2 schrieb Jeffrey R. Carter:
> On 10/16/18 11:57 AM, AdaMagica wrote:
> > 
> > OK. In function Password_Generation.Generate, what are Domain and Master for?
> > What does Hash_Symbol do?
> 
> Good points. This was extracted from a more monolithic, earlier version of 
> Password_Gen, where perhaps these concepts were better explained, and I didn't 
> think to clarify them when I pulled them out. I'll try to explain these better.

Yes. Even inner specs that are not visible for the user must follow these rules that everything visible in the spec is exactly described. Then nothing bad happens when an internal package is extracted.

> > What does "correctness of the implementation" mean for this package?
> 
> That the function returns the same password for the same inputs, and the 
> passwords have all the desirable features for generated passwords:  they appear 
> random, contain characters from all the major food groups, and give away nothing 
> about the master password.

This is what I mean. There is no requirement defined for this operation. So how can I as a user know what I get? So you have to put this in the spec as a description. Then a user can make test to check whether the claims are true.

Christoph

Re: Is the Documentation In a spec File Usually Enough For You ?

[Brad Moore]

It should also be mentioned that with Ada 2012, the addition of contracts helps also aid to reader of a spec understand what a subprogram does, and how it was intended to be used by the author. 

A problem with documentation is that it can become stale if not maintained, whereas the contracts are assertions in the code and thus tend to be more accurate. 

A designer of a package should consider, for example, what pre and post conditions should be applied to the subprograms of that package. The addition of contracts tends to simplify the documentation that is needed.

As an example, in the standard package
Ada.Locales, there is;

   type Country_Code is new String (1 .. 2)
      with Dynamic_Predicate =>
         (for all E of Country_Code => E in 'A' .. 'Z');

 function Country return Country_Code;

If we didn't have the contract for Dynamic_Predicate on the Country_Code type, 
we would need to document that the function Country returns a 2 character string where all the characters of the string consist of capital letters from A to Z inclusive.  

With the contract, this doesn't need to be documented, and the contract is more concise for the reader than having to read a full paragraph of text. Further, anywhere the Country_Code result is used in the user's program, it is clear that the contract holds, since it is a property of the type.

If the implementation changes in a way that breaks the contracts, then this tends to get caught, and either the implementation is adjusted to meet the contracts, or the contracts are adjusted to meet the implementation. Generally one tries to avoid making changes to contracts, particularly if there are existing users of those contracts.

Brad

Re: Is the Documentation In a spec File Usually Enough For You ?

[Jeffrey R. Carter]

On 10/18/18 11:06 AM, AdaMagica wrote:
> Am Dienstag, 16. Oktober 2018 18:57:51 UTC+2 schrieb Jeffrey R. Carter:
>>
>> That the function returns the same password for the same inputs, and the
>> passwords have all the desirable features for generated passwords:  they appear
>> random, contain characters from all the major food groups, and give away nothing
>> about the master password.
> 
> This is what I mean. There is no requirement defined for this operation. So how can I as a user know what I get? So you have to put this in the spec as a description. Then a user can make test to check whether the claims are true.

I'm not sure I agree. This is package Password_Generation, function Generate, a 
service to generate passwords. I think that is clear from the code and needs no 
further explanation. The description above is simply the definition of a good 
generated password.

I don't think this spec should be a tutorial on password generation. Someone 
looking at it wants to generate passwords, and should know why one generates 
passwords and what the qualities of a good generated password are.

-- 
Jeff Carter
"Well, a gala day is enough for me. I don't think
I can handle any more."
Duck Soup
93

Re: Is the Documentation In a spec File Usually Enough For You ?

[AdaMagica]

Am Donnerstag, 18. Oktober 2018 19:29:16 UTC+2 schrieb Jeffrey R. Carter:
> On 10/18/18 11:06 AM, AdaMagica wrote:
> > Am Dienstag, 16. Oktober 2018 18:57:51 UTC+2 schrieb Jeffrey R. Carter:
> >>
> >> That the function returns the same password for the same inputs, and the
> >> passwords have all the desirable features for generated passwords:  they appear
> >> random, contain characters from all the major food groups, and give away nothing
> >> about the master password.
> > 
> > This is what I mean. There is no requirement defined for this operation. So how can I as a user know what I get? So you have to put this in the spec as a description. Then a user can make test to check whether the claims are true.
> 
> I'm not sure I agree. This is package Password_Generation, function Generate, a 
> service to generate passwords. I think that is clear from the code and needs no 
> further explanation. The description above is simply the definition of a good 
> generated password.
> 
> I don't think this spec should be a tutorial on password generation. Someone 
> looking at it wants to generate passwords, and should know why one generates 
> passwords and what the qualities of a good generated password are.

So just say WHAT it does, not HOW it does.

If you do not say that your code produces a good password, how can the user know he will get a good password? He must trust JC because he possibly knows him personally or because he uses other well defined and well written sw from him.

But I claim: In SW, there must be no such trust. JC may just have been being lazy in this case.

And I further claim there are tons of bad SW around. Just because a unit's name says XXX, there is no guarantee that it indeed does XXX.

If I were looking for password generators, I would not waste my time in trying some that don't claim to produce good ones; instead I'd pick one with such a claim and test it thoroughly. 

Re: Is the Documentation In a spec File Usually Enough For You ?

[Dennis Lee Bieber]

On Thu, 18 Oct 2018 10:54:23 -0700 (PDT), AdaMagica
<christ-usch.grein@t-online.de> declaimed the following:

>
>If I were looking for password generators, I would not waste my time in trying some that don't claim to produce good ones; instead I'd pick one with such a claim and test it thoroughly. 

	If you are going to "test it thoroughly" it doesn't matter what it
claims or doesn't claim. You pick it, test it, and decide if it meets your
needs. If it doesn't, pick a different one and repeat the testing. The
generator is a black-box; everything you know about it is from testing as a
black-box -- no knowledge of internals.

I, at least, wouldn't necessarily believe a spec file that states
"generates highly secure passwords" -- when all it might really be doing is
a cycle a 16-character string through the BASE64 character set (first
password AAAAAAAAAAAAAAA, next, AAAAAAAAAAAAAAB, etc.)




-- 
	Wulfraed                 Dennis Lee Bieber         AF6VN
	wlfraed@ix.netcom.com    HTTP://wlfraed.home.netcom.com/ 

Re: Is the Documentation In a spec File Usually Enough For You ?

[Jeffrey R. Carter]

On 10/18/18 7:54 PM, AdaMagica wrote:
> 
> If you do not say that your code produces a good password, how can the user know he will get a good password? He must trust JC because he possibly knows him personally or because he uses other well defined and well written sw from him.
> 
> But I claim: In SW, there must be no such trust. JC may just have been being lazy in this case.

Right. So if I claim the function returns a good password, you won't trust me 
and won't accept my claim until you've tested it. So there's no point in my 
making such a claim.

-- 
Jeff Carter
"Well, a gala day is enough for me. I don't think
I can handle any more."
Duck Soup
93

Re: Is the Documentation In a spec File Usually Enough For You ?

[Randy Brukardt]

"AdaMagica" <christ-usch.grein@t-online.de> wrote in message 
news:80e23f09-06ac-4112-9b7f-e765266a952d@googlegroups.com...
...
> If I were looking for password generators, I would not waste my time
>in trying some that don't claim to produce good ones; instead I'd pick
>one with such a claim and test it thoroughly.

I'd also want some documentation as to what the author considers a "good" 
password, as the advice for that seems to change every few years. I'd guess 
that this package was based on some advice from a few years ago, so it might 
not even be "good" anymore. (That's certainly the case with a lot of Ada 
libraries, which haven't been modified for a long time as no one has seen a 
need to do so.)

After all, "good" is not a technical term, in any field that I'm aware of.

Certainly, you don't need to put this sort of documentation on individual 
subprograms; it belongs to the library as a whole. But without it, you 
really can't judge fitness.

                                        Randy.

Re: Is the Documentation In a spec File Usually Enough For You ?

[J-P. Rosen]

Le 18/10/2018 à 23:24, Randy Brukardt a écrit :
> After all, "good" is not a technical term, in any field that I'm aware of.
However, quoting A.4.9(12/2):
   "The Hash functions should be good hash functions..."

Admitedly, it's only implementation advice ;-)

-- 
J-P. Rosen
Adalog
2 rue du Docteur Lombard, 92441 Issy-les-Moulineaux CEDEX
Tel: +33 1 45 29 21 52, Fax: +33 1 45 29 25 00
http://www.adalog.fr

Re: Is the Documentation In a spec File Usually Enough For You ?

[Randy Brukardt]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain, Size: 738 bytes --]

"J-P. Rosen" <rosen@adalog.fr> wrote in message 
news:pqc1nf$5tb$1@gioia.aioe.org...
> Le 18/10/2018 à 23:24, Randy Brukardt a écrit :
>> After all, "good" is not a technical term, in any field that I'm aware 
>> of.
> However, quoting A.4.9(12/2):
>   "The Hash functions should be good hash functions..."
>
> Admitedly, it's only implementation advice ;-)

Exactly. One of the most meaningless statements in the RM. Note that this 
statement goes on to give a description of what it means: "...returning a 
wide spread of values for different string values. It should be unlikely for 
similar strings to return the same value." That's the important part; "good" 
really doesn't add anything here.

                             Randy.

Re: Is the Documentation In a spec File Usually Enough For You ?

[AdaMagica]

Am Donnerstag, 18. Oktober 2018 22:07:18 UTC+2 schrieb Jeffrey R. Carter:
> On 10/18/18 7:54 PM, AdaMagica wrote:
> > 
> > If you do not say that your code produces a good password, how can the user know he will get a good password? He must trust JC because he possibly knows him personally or because he uses other well defined and well written sw from him.
> > 
> > But I claim: In SW, there must be no such trust. JC may just have been being lazy in this case.
> 
> Right. So if I claim the function returns a good password, you won't trust me 
> and won't accept my claim until you've tested it. So there's no point in my 
> making such a claim.

So if you used a library written by me, would you take it as is without ever caring whether is does what I claimed that it does? How imprudent!

Re: Is the Documentation In a spec File Usually Enough For You ?

[Jeffrey R. Carter]

On 10/21/18 5:20 PM, AdaMagica wrote:
> Am Donnerstag, 18. Oktober 2018 22:07:18 UTC+2 schrieb Jeffrey R. Carter:
>>
>> Right. So if I claim the function returns a good password, you won't trust me
>> and won't accept my claim until you've tested it. So there's no point in my
>> making such a claim.
> 
> So if you used a library written by me, would you take it as is without ever caring whether is does what I claimed that it does? How imprudent!

It appears that you have significantly misunderstood what I wrote.

-- 
Jeff Carter
"Sir Lancelot saves Sir Gallahad from almost certain temptation."
Monty Python & the Holy Grail
69

Re: Is the Documentation In a spec File Usually Enough For You ?

[AdaMagica]

Am Sonntag, 21. Oktober 2018 20:56:40 UTC+2 schrieb Jeffrey R. Carter:
> On 10/21/18 5:20 PM, AdaMagica wrote:
> > Am Donnerstag, 18. Oktober 2018 22:07:18 UTC+2 schrieb Jeffrey R. Carter:
> >>
> >> Right. So if I claim the function returns a good password, you won't trust me
> >> and won't accept my claim until you've tested it. So there's no point in my
> >> making such a claim.
> > 
> > So if you used a library written by me, would you take it as is without ever caring whether is does what I claimed that it does? How imprudent!
> 
> It appears that you have significantly misunderstood what I wrote.

OK, let's put it in a different way.

There is a library written by me called XYZ, but I do not claim anything about reliability etc. And there are many others out there also doing XYZ. Which one would you chose? I guess the one with the optimal documentation, but definitely not mine; and you will test it, wouldn't you?

Re: Is the Documentation In a spec File Usually Enough For You ?

[Jeffrey R. Carter]

On 10/22/18 6:04 PM, AdaMagica wrote:
> 
> There is a library written by me called XYZ, but I do not claim anything about reliability etc. And there are many others out there also doing XYZ. Which one would you chose? I guess the one with the optimal documentation, but definitely not mine; and you will test it, wouldn't you?

I'm not talking about me. I'm talking about your statement that you don't trust 
any S/W, and the logical consequences of that towards claims made by authors 
about their S/W. If an author makes a claim, you won't trust it until you've 
tested it, because you don't trust S/W. If an author makes no claim, that 
shouldn't change anything, because you have the same trust in that S/W that you 
have in S/W with a claim: none until you've tested it. Yet you seem to say that 
between a library that makes a claim of goodness and another with no claim, 
you'd choose the one with the claim, despite having equal lack of trust in both.

-- 
Jeff Carter
"It's all right, Taggart. Just a man and a horse being hung out there."
Blazing Saddles
34

Re: Is the Documentation In a spec File Usually Enough For You ?

[AdaMagica]

Am Montag, 22. Oktober 2018 21:13:33 UTC+2 schrieb Jeffrey R. Carter:
> On 10/22/18 6:04 PM, AdaMagica wrote:
> > 
> > There is a library written by me called XYZ, but I do not claim anything about reliability etc. And there are many others out there also doing XYZ. Which one would you chose? I guess the one with the optimal documentation, but definitely not mine; and you will test it, wouldn't you?
> 
> I'm not talking about me. I'm talking about your statement that you don't trust 
> any S/W, and the logical consequences of that towards claims made by authors 
> about their S/W. If an author makes a claim, you won't trust it until you've 
> tested it, because you don't trust S/W. If an author makes no claim, that 
> shouldn't change anything, because you have the same trust in that S/W that you 
> have in S/W with a claim: none until you've tested it. Yet you seem to say that 
> between a library that makes a claim of goodness and another with no claim, 
> you'd choose the one with the claim, despite having equal lack of trust in both.

We all are fond of Ada and trust the compilers and like the portability of Ada's code. Why? Because there is the ACATS (the former ACVC) test suite. And according to Randy, many compilers have great difficulties to fulfil the last x% of the ACATS.

So tests of SW are a kind of sine qua non.