[llvm-dev] Questions on Clang's documentation of Modules

[Dan Liew via llvm-dev]

> Yes. The rest of the module is part of the program in the same way that
> other .o files that are linked to the current one are part of the program.
> But the import only makes the nominated submodule visible.
>
> Put another way: top-level modules are the units of granularity for linking,
> and submodules are the units of granularity for visibility within a
> particular translation unit. But because the compiler knows that the entire
> top-level module will be part of the program when a submodule is imported,
> it's able to diagnose more problems / conflicts.

Okay thanks for clarifying.

>> # Use declaration
>>
>> I don't understand this part at all.
>>
>> What does ``the current top-level module`` mean here? In other places
>> the docs say "enclosing module" for other declarations inside a module
>> declaration. Are these supposed to be the same? They do not sound the
>> same.
>
>
> A top-level module is one that's not a submodule of another module.  We can
> easily add a definition if that's not obvious.
>
> Example:
>
> module A {
>   module B {
>     module C {
>       // Here, A is the top-level module, but A.B.C is the (immediately)
> enclosing module.

Okay that makes sense now.

> In any case, I think the documentation is a little unclear here: we should
> probably phrase this as "A use-declaration specifies another module that the
> enclosing module (that is required to be a top-level module) intends to
> use." or similar.

That seems like a better explanation.

>> The example given further confuses me because
>>
>> - I don't know what the "current top-level module" is here
>> - I don't understand why the compiler would complain about anything
>> here. There's nothing here that indicates that "c.h" depends on "a.h"
>> so why would the compiler complain about module C not declaring a
>> dependency on module A.
>
>
> It says that "use of A from C" would trigger a warning, that is, if C
> included one of A's headers, a warning would be triggered. This would be a
> lot more obvious if we gave example contents for c.h.

That's not how I read it. It currently says

```
In the following example, use of A from C is not declared, so will
trigger a warning.
```

To me this is stating that

"use of A from C is not declared in the module map" (i.e. there is no
``use A`` in the declaration of module C in the module map).

and I intuitively expect that

"use of symbols in A from C" and "use of A from C is not declared in
the module map" imply a warning will be raised.

However nothing states whether "use of symbols in A from C" is true or
false so I cannot concluded if a warning will be raised.

I think cleaning up the wording and example contents of the header
would remove confusion here.

I'll try to write a patch and I'll CC you.

Thanks,
Dan.


it **will trigger a warning**. Given the intention here the wording i

-- 
Dan Liew
PhD Student - Imperial College London