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

[Simon Taylor]

On 15-Nov-2001, Fergus Henderson <fjh at cs.mu.OZ.AU> wrote:
> 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 @@
> > -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.

I've added a description of the method to convert a separate sub-module
into a nested sub-module to show how the semantics are identical.
 
> > +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.

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

> 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.)

Done.

--- reference_manual.texi
+++ reference_manual.texi
@@ -3684,0 +3685,3 @@
+As mentioned earlier, it is an error to define a sub-module in the
+interface section of its parent module.
+
@@ -3725 +3728,16 @@
-sub-modules.
+sub-modules. The procedure to transform a separate sub-module into a
+nested sub-module is as follows:
+
+ at enumerate
+ at item
+Replace the @samp{:- include_module @var{submodule}} declaration with
+the interface section of the sub-module enclosed within 
+ at samp{:- module @var{submodule}} and @samp{:- end_module @var{submodule}}
+declarations.
+ at item
+Place the implementation section of the sub-module enclosed within
+ at samp{:- module @var{submodule}} and @samp{:- end_module @var{submodule}}
+declarations in the implementation section of the parent module.
+ at end enumerate
+
+For example
@@ -3733,0 +3752 @@
+ at noindent
@@ -3766,4 +3785,4 @@
-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.
+Note that a sub-module for which the @samp{:- module} or
+ at samp{:- include_module} declaration occurs only in the implementation
+section of the parent module may only be imported or used by its
+parent module or by sub-modules of its parent module.


--------------------------------------------------------------------------
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
--------------------------------------------------------------------------