Re: Question about record rep spec placement

[Ken Garlington <GarlingtonKE@lmtas.lmco.com>]

Bob Gilbert wrote:
> 
> If you really don't want the user to make assumptions
> regarding the internals of the type, why not just go ahead and
> make it a private type?

Because I may be willing for the client to use information about
the number, names, and types of record components (for example),
but not their starting bit position, bit width, etc.

> Placing the rep spec of a non-private
> type in the private section (if allowed) does not communicate any
> information to the compiler and may confuse the reader.

Our experience so far is that this helps the reader. (It's in an
interface to an OS we develop, with several end users spread out
over several companies). I don't know if it communicates any more
information to the compiler; since we write the code with an
emphasis on communicating to the human reader, we don't get too
excited about compiler issues (so long as the code works, of course!)

>  Seems
> like some judicious use of comments might be in order.

Why write comments for things that Ada allows you to express
directly?

> 
> > (2) We have a tool that takes Ada code and inserts it into documentation
> > developing using the Interleaf document processor. It makes keywords
> > bold, and all of that, and it also has an option to suppress listing the
> > information in the private section. So, if we don't want details to appear
> > in our user documentation, we put it in the private section.
> 
> Okay, but it still seems like a kludge and an abuse to me.

OK. As I said, it seems to work well in real life, so we're sticking to
it. :)

> 
> That said, I do admit that sometimes having to include rep specs in
> the same declaration list as the entity it refers to, adds unnecessary
> verbosity to a package specification where the user would probably
> have little or no use for the knowledge of the type's representation.

Well, there you go!

> It might be useful to somehow identify a type as requiring a rep
> spec, but be able to provide the details elsewhere (say within
> the package body, or a representation section that works similar to
> the private section).  Say something like: <hair-brained idea mode on>
> 
>   type T is {whatever};
>   for type T use private;  -- Tell the user and compiler to look for
>                            -- further specifics about T's representation
>                            -- elsewhere in the package, perhaps even in
>                            -- the package body.

Today, of course, you can do this with one less line (don't need the
"for type..."),
which is even _less_ verbose!

You seem to believe that the client of a package is usually expected to
read the
private part. Our philosophy is that they probably shouldn't - when they
hit "private",
they stop reading (and as I said, we even enforce that in our user
documentation!)

> 
> -Bob

--
LMTAS - The Fighter Enterprise - "Our Brand Means Quality"
For job listings, other info: http://www.lmtas.com or
http://www.lmco.com