[m-rev.] for review: delete quotes from `VarNames' in stdlib comments

[Zoltan Somogyi]

2022-03-07 11:30 GMT+11:00 "Julien Fischer" <jfischer at opturion.com>:
> 
> On Mon, 7 Mar 2022, Zoltan Somogyi wrote:
> 
>> Delete quotes from `VarNames' in stdlib comments.
>> > In the Mercury standard library, every exported predicate or function
>> has (or at least *should* have) a comment that documents it, including
>> the meanings of its arguments. About 35-40% of these modules put `'s
>> (left and right quotes) around the names of the variable representing
>> those arguments. Some tried to do it consistently (though there were spots
>> with unquoted or half quoted names), while some did it only a few places.
>> This is inconsistent: we should either do it everywhere, or nowhere.
>> This diff makes it nowhere, because
>> > - this is what the majority of the standard library modules do;
>> - this is what virtually all of the modules in the compiler, profiler,
>>   deep_profiler etc directories do; and because
>> - typing all those quotes when adding new predicates in modules that
>>   follow this convention is a pain in the ass.
>> > Likewise, the comment explaining a predicate often started with
>>
>>     % `predname(arguments)' returns ...
>> > This diff deletes these quotes as well, since they add nothing useful.
>> > This diff does leave in place quotes around code fragments, both terms
>> and goals, where this helps delineate the boundaries of that fragment.
> 
> Another reason is that we are no longer using xterms in the 1990s and
> with the fonts in modern terminals, `' looks non-symmetrical and weird.

I added this as a reason in the log message.

> Perhaps,
> 
>     The universial type: univ.
> 
> ?
> 
> I suggest also updating the "Standard library predicates" section of
> the coding standard to document the quoting convention for comments
> in the standard library.

The attached diff, whose two parts I just committed separately,
addresses this.

> The diff looks fine otherwise.

Thanks for the review.

Zoltan.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: DIFF.nq2
Type: application/octet-stream
Size: 1922 bytes
Desc: not available
URL: <http://lists.mercurylang.org/archives/reviews/attachments/20220307/f9a2356c/attachment.obj>