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

[Dan Liew via cfe-dev]

Hi,

I was reading Clang's documentation [1] on Modules and there are
several aspects that confused me that I was wondering if someone could
clarify some parts. I'm CC'ing a few people who git blame shows
contributed to the documentation. Hopefully answers can be used to
help me write a patch to improve the documentation here.

# Modules Semantics

The following is stated

```
If any submodule of a module is imported into any part of a program,
the entire top-level module is considered to be part of the program.
As a consequence of this, Clang may diagnose conflicts between an
entity declared in an unimported submodule and an entity declared in
the current translation unit, and Clang may inline or devirtualize
based on knowledge from unimported submodules.
```

What does considered "part of the program" mean here? Initially I
thought that meant just import the parent module (i.e. writing
``import std.io`` is the same as ``import std``) but thinking about it
some more that doesn't make sense because there wouldn't be any point
in having submodules because they couldn't be used independently from
other submodules.

Perhaps what was meant here is that because ``std`` corresponds to one
or more libraries we can have Clang check for problems that might
occur if the program did do ``import std`` (i.e. we used more of the
library that we are linking against) even though it isn't. Is that
correct?

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

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.

Any insight here would be appreciated.

[1] http://clang.llvm.org/docs/Modules.html

Thanks,
Dan.