Re: Is there a way to do large block of source code comments

["G.B." <bauhaus@futureapps.invalid>]

On 01.09.14 22:53, Niklas Holsti wrote:
>> Ada 2012 aspect notation could add a tool-ready aspect that describes
>> >an entity in brief:
>> >
>> >   procedure Read (..., Item : out T)
>> >      with Comment => "... short description ...",
> That could be useful for ASIS tools (although I believe that ASIS
> already has some way to access the comments for a declaration), but I
> would object to using the word "Comment" as the aspect name, for the
> reasons I have given.

This aspect seems so easy to implement, yet so simple, useful,
and widespread (across languages) as to have a chance of being
acceptable as an addition to Ada. (GNAT, in particular, already
has Annotate, which is a lot more elaborate.)

Should I send this:

!topic An aspect for associating brief descriptions with declarations
!reference Ada 2012 RM 3, 6.1.1, K
!from Georg Bauhaus 14-09-02
!keywords aspects comments ASIS
!discussion

Starting with the Ada 83 style guide, there is advise on
commenting, a controversial yet much needed part of all
programs. The Ada language dispenses with any controversy by
simply providing the rules of “--” at the level of syntax. Tools
associating comments and declarations usually require some ad-hoc
convention that is not universal, which hinders integration. This
partly contrasts with Section 3.3 of the guidelines which state

  "o    Structure comments in headers so that information can be
        automatically extracted by a tool."


On the other hand, in Ada 2012, there now is a way for programmers
to "explain aspects of the code that are otherwise not
readily apparent." [ibid.]. This can be achieved, in part, by using
the contract related aspects of RM 6.1.1. Similarly, a standard
aspect for things still not readily apparent could be hooked to
an aspect, as explained below.

The focus of this aspect would be on indexes as found in books,
slightly adapted to the needs of programmers. For example, in
larger programming situations, it will be beneficial to have an
index of an Ada library that lists the entities declared therein
together with a short description, readable without reference to a
number of ad-hoc conventions for associating comments and
declarations. That is, for index style commenting to be useful
across projects, compilers, and tools, the name of a corresponding
aspect needs to be standardized.

It's value would be a string.

The idea is to have a very simple mechanism, easy to implement and
usable with tools simpler than ASIS (but not excluding the latter).
It is a compromise between today's implied, ad-hoc rules of comment
placement and a more express solution. The Java language is offering
@-keywords for this purpose; they are more elaborate, yet less
flexible.

An additional benefit of closer integration of "indexing comments"
with the language is that failing to update comments might be less
likely, because an aspect appears more pressing on change than
just about anything that can be put behind “--”, somewhere.

package Example
   with Indexing=> "declarations illustrating this submission"
is
    -- Not all comments are about one thing in particular.
    -- Not all comments are very brief.
    -- Some comments seem to have no reference at all.

    Buckets : Natural := 12
      with Indexing => "number of buckets configured",
        Atomic;

    function Drops (Bucket : Natural) return Natural
      with Indexing => "number of drops collected in Bucket",
        Post => (if Drops'Result = 0
                 then (not Is_Placed (Bucket) or No_Rain));
    -- TODO: replace Natural with a subtype for bucket numbering

end Example;