[m-rev.] for review: improve sub-modules documentation

[Fergus Henderson]

On 15-Nov-2001, Simon Taylor <stayl at cs.mu.OZ.AU> wrote:
> 
> doc/reference_manual.texi:
> 	Improve the documentation of sub-modules.
> 
> Index: reference_manual.texi
> ===================================================================
> RCS file: /home/mercury1/repository/mercury/doc/reference_manual.texi,v
> retrieving revision 1.224
> diff -u -u -r1.224 reference_manual.texi
> --- reference_manual.texi	12 Nov 2001 11:08:13 -0000	1.224
> +++ reference_manual.texi	15 Nov 2001 06:26:12 -0000
> @@ -3721,14 +3721,30 @@
>  Mercury implementation requires the module name in the @samp{:- module}
>  declaration for that module to be fully qualified.)
>  
> -If an @samp{:- include_module} declaration occurs in the interface
> -section of a module, then only the declarations (interfaces) of the sub-modules
> -are included in the parent module's interface; the definitions
> -(implementations) of the sub-modules are considered to be implicitly
> -part of the parent module's implementation.
> -
> -Apart from that, the semantics of separate sub-modules are
> -identical to those of nested sub-modules.
> +The semantics of separate sub-modules are identical to those of nested
> +sub-modules.
> + at example
...

The text you deleted here is important.

Without this text, programs using separate sub-modules would violate the
requirement that "The implementation section must contain definitions
for all ... sub-modules exported by the module" (from the "The module
system" section of the "Modules" chapter).

Another problem is that in your modified version, the example includes
things which can't be deduced from the other text.  It is useful to
include an example, but the semantics can't be defined by example.
Examples should just illustrate what has been specified earlier.

> @@ -3739,10 +3755,18 @@
>  Similarly, declarations in the interfaces of any modules imported using an
>  @samp{:- import_module} or a @samp{:- use_module} in the parent module
>  are visible in the parent's sub-modules, including indirect sub-modules.
> -However, declarations in a child module are not visible in the parent
> -module or in "sibling" modules (other children of the same parent)
> -unless the child is explicitly imported using an @samp{:- import_module}
> -or @samp{:- use_module} declaration. 
> +
> +Declarations in a child module are not visible in the parent module,
> +or in "sibling" modules (other children of the same parent), or in
> +other unrelated modules unless the child is explicitly imported using
> +an @samp{:- import_module} or @samp{:- use_module} declaration.

Fine.

> +It
> +is an error to import a module without importing all of its parent
> +modules.

Fine.

> +A sub-module for which the @samp{:- module} or @samp{:- include_module}
> +declaration occurs only in the implementation section of the parent module
> +is an implementation sub-module. It may only be imported or used by its
> +parent module.

... or by sub-modules of its parent module.

Also, s/is an/is called an/?

In fact this is a direct consequence of a requirement already stated elsewhere:

 |    An `:- implementation.' declaration indicates the start of the
 |    module's implementation section.  Any entities declared in this section
 |    are local to the module (and its sub-modules) and cannot be used by
 |    other modules.

"Any entities" includes sub-modules, and "this section" refers to
"the module's implementation section", so we have

 |    Any [submodules] declared in [the module's implementation section]
 |    are local to the module (and its sub-modules) and cannot be used by
 |    other modules.

Including redundancy can be good, because it can make it easier for
readers to understand.  But we should be careful to distinguish text
that is just redundantly repeating requirements stated earlier, for the
sake of clarity, from text which is adding new requirements.  Hence
I suggest you start this with "Note that ...", which is the phrase
used in other parts of the reference manual for such material.

(Although you may have to rephrase it to make it clear that the
"Note that" applies to the whole paragraph.)

-- 
Fergus Henderson <fjh at cs.mu.oz.au>  |  "I have always known that the pursuit
The University of Melbourne         |  of excellence is a lethal habit"
WWW: <http://www.cs.mu.oz.au/~fjh>  |     -- the last words of T. S. Garp.
--------------------------------------------------------------------------
mercury-reviews mailing list
post:  mercury-reviews at cs.mu.oz.au
administrative address: owner-mercury-reviews at cs.mu.oz.au
unsubscribe: Address: mercury-reviews-request at cs.mu.oz.au Message: unsubscribe
subscribe:   Address: mercury-reviews-request at cs.mu.oz.au Message: subscribe
--------------------------------------------------------------------------