[m-rev.] for review: coding standard change - module qualification in stdlib interfaces

[Paul Bone]

On Thu, Oct 09, 2014 at 02:54:13PM +1100, Julien Fischer wrote:
>
> For review by anyone:
>
> The actual addition is at the very last bit of the diff.
> It probably doesn't require much in the way of a review bar
> a "yay" or a "nay" from everyone.

Yay,

This is something I'd considered for a while but hadn't thought to make it
official.  I'm also about to make this change to thread.mvar.m

>
> --------------------
>
> Coding standard change: module qualification in library interfaces.
>
> compiler/notes/coding_standards.html:
> 	Specify that library module interfaces should avoid module
> 	qualification where possible.
>
> 	Minor formatting improvements and (a few) rewordings.
>
> Julien.
>
> diff --git a/compiler/notes/coding_standards.html b/compiler/notes/coding_standards.html
> index 709cb3e..68c546c 100644
> --- a/compiler/notes/coding_standards.html
> +++ b/compiler/notes/coding_standards.html
> @@ -457,10 +457,10 @@ since this makes it harder to resort the group with a single editor command.
>
>  <h2> Standard library predicates </h2>
>
> -The descriptive comment for any predicate or function
> -that occurs in the interface of a standard library module
> -must be positioned above the predicate/function declaration.
> -It should be formatted like the following example: +The descriptive 
> comment for any predicate or function that occurs in the
> +interface of a standard library module must be positioned above the predicate
> +or function declaration.
> +It should be formatted as in following example:
>
>  <pre>
>
> @@ -470,11 +470,10 @@ It should be formatted like the following example:
>  	:- mode foo(...
>  </pre>
>
> -A group of related predicate, mode and function declarations
> -may be grouped together under a single description
> -provided that it is formatted as above.
> -If there is a function declaration in such a grouping
> -then it should be listed before the others. +A group of related 
> predicate, mode and function declarations may be grouped
> +together under a single description provided that it is formatted as above.
> +If there is a function declaration in such a grouping then it should be listed
> +before the others.
>
>  For example:
>
> @@ -483,15 +482,19 @@ For example:
>  		% Insert a new key and corresponding value into a map.
>  		% Fail if the key already exists.
>  		%
> -	:- func map.insert(map(K, V), K, V) = map(K, V).
> -	:- pred map.insert(map(K, V)::in, K::in, V::in, map(K, V)::out) is det.
> +	:- func insert(map(K, V), K, V) = map(K, V).
> +	:- pred insert(map(K, V)::in, K::in, V::in, map(K, V)::out) is det.
>
>  </pre>
>
> -The reason for using this particular style is that
> -the reference manual for the standard library
> -is automatically generated from the module interfaces,
> -and we want to maintain a uniform appearance as much as is possible.
> +The reason for using this particular style is that the reference manual for the
> +standard library is automatically generated from the module interfaces, and we
> +want to maintain a uniform appearance as much as is possible.
> +
> +<p>
> +
> +Avoid module qualification in the interface sections of library modules except
> +where necessary to resolve ambiguity.
>
>  <h2> Testing </h2>
>
>
> _______________________________________________
> reviews mailing list
> reviews at lists.mercurylang.org
> https://www.mercurylang.org/lists/listinfo/reviews

-- 
Paul Bone