[m-rev.] for review: Document that `:- module' for separate submodules must be fully qualified.

[Julien Fischer]

Hi Zoltan,

On Tue, 14 Jan 2020, Zoltan Somogyi wrote:

> 2020-01-14 16:08 GMT+11:00 Julien Fischer<jfischer at opturion.com>:
>> s/sub-module/submodule/ for consistency with the rest of the file.
>> (Actually, perhaps we should do the reverse in the NEWS file since the
>> rest of the Mercury documentation seems to use sub-module.)
>
> I agree that consistency is important, but I would quite strongly prefer
> that we standardize on submodule over sub-module.

That's fine by me; I'll got through the documentation and adjust it.
(Assuming no-one else beats me to it.)

>>> @@ -5358,16 +5358,9 @@ with a list of the file names of all the Mercury modules in the program.)
>>> The source file of a separate sub-module must contain
>>> the declaration (interface) and definition (implementation) of the sub-module.
>>> It must start with a @samp{:- module} declaration
>>> -which matches that in the @samp{:- include_module} declaration in the parent,
>>> +containing the fully qualified module name,
>>> followed by the interface and (if necessary) implementation sections,
>>> and it may optionally end with a @samp{:- end_module} declaration.
>>
>> And is that end_module declaration allowed to be not fully qualified?
>
> At the moment IIRC, it may be anything that passes the "partial_sym_name_
> matches_full" test on the name of the module being closed.
>
> There is a constraint on what module names may appear in end_module declarations.
> The constraint is that it has to unambiguously specify that the module being ended
> is the module we are currently in, and NOT some containing module. This is because
> after ":- module a" and ":- module a.b", if we next we see ":- end_module a", then
> the end_module for a.b is missing. We have an error message specifically for that.

The issue is that Peter's original diff deleted the bit saying what is
allowed.  (Which reads oddly, because we make a point of saying what is
allowed for nested submodule but not separate ones.)

>>> -(Note: the module names in the @samp{:- module}, @samp{:- end_module},
>>> -and @w{@samp{:- include_module}} declarations need not be fully-qualified.
>>> -However, if the file name used for a particular module
>>> -does not include all the module qualifiers,
>>> -then the Melbourne Mercury implementation
>>> -requires the module name in the @samp{:- module} declaration
>>> -for that module to be fully qualified.)
>>
>> There is now nothing (I think) saying whether the names appearing in
>> include_module declarations should be qualified, unqualified, partially
>> qualified etc. I think there needs to be.
>
> For include_module declarations, the qualification as written in the code
> is not very important, because the included module's fully qualified name
> *has to be* the fully qualified name of the including module, followed by
> the name of the submodule. This means that the only kind of wrong qualification
> is the one that does not pass the "partial_sym_name_matches_full" test
> on the fully qualified name of the included module.

By "not very important", you presumably mean "completely redundant". ;-)
That said, the reference manual should still say what is allowed.

In the past, IIRC, there we bugs in mmc --make that required
include_module declarations to be fully qualified, so it's likely that
there is existing code that has fully qualified include_module
declarations.  (The Zinc compiler being one such piece of code.)

Julien.