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=-0.3 required=5.0 tests=BAYES_00, REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4 Path: border1.nntp.dca1.giganews.com!border2.nntp.dca1.giganews.com!nntp.giganews.com!usenet.blueworldhosting.com!feeder01.blueworldhosting.com!eternal-september.org!feeder.eternal-september.org!news.eternal-september.org!.POSTED!not-for-mail From: "G.B." Newsgroups: comp.lang.ada Subject: Re: Is there a way to do large block of source code comments Date: Tue, 02 Sep 2014 15:14:48 +0200 Organization: A noiseless patient Spider Message-ID: References: <1285756762431293678.582499nonlegitur-futureapps.invalid@reader80.eternal-september.org> Reply-To: nonlegitur@futureapps.de Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: 8bit Injection-Date: Tue, 2 Sep 2014 13:14:45 +0000 (UTC) Injection-Info: mx05.eternal-september.org; posting-host="b96887e80893c84a90c3007226ca0d1c"; logging-data="26842"; mail-complaints-to="abuse@eternal-september.org"; posting-account="U2FsdGVkX19aiaPLkcRYiWnOr9xYNrkDHO9/oz6mLnY=" User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.9; rv:24.0) Gecko/20100101 Thunderbird/24.6.0 In-Reply-To: Cancel-Lock: sha1:NHSTFB+H4Tr3N3vvKfJ5KzpzUK8= Xref: number.nntp.dca.giganews.com comp.lang.ada:188800 Date: 2014-09-02T15:14:48+02:00 List-Id: 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;