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

[Zoltan Somogyi]

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.

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

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

Zoltan.