[flang-commits] [flang] [flang][NFC] Update module file documentation (PR #135107)

[via flang-commits]

================
@@ -14,138 +14,136 @@ local:
 ---
 ```
 
-Module files hold information from a module that is necessary to compile 
-program units that depend on the module.
+Module files hold information from a module (or submodule) that is
+necessary to compile program units in other source files that depend on that module.
+Program units in the same source file as the module do not read
+module files, as this compiler parses entire source files and processes
+the program units it contains in dependency order.
 
 ## Name
 
-Module files must be searchable by module name. They are typically named
-`<modulename>.mod`. The advantage of using `.mod` is that it is consistent with
-other compilers so users will know what they are. Also, makefiles and scripts
-often use `rm *.mod` to clean up.
+Module files are named according to the module's name, suffixed with `.mod`.
+This is consistent with other compilers and expected by makefiles and
+other build systems.
+
+Module files for submodules are named with their ancestor module's name
+as a prefix, separated by a hyphen.
+E.g., `module-submod.mod` is generated for submodule `submod' of module
+`module`.
+Some other compilers use a distinct filename suffix for submodules,
+but this one doesn't.
 
 The disadvantage of using the same name as other compilers is that it is not
 clear which compiler created a `.mod` file and files from multiple compilers
-cannot be in the same directory. This could be solved by adding something
-between the module name and extension, e.g. `<modulename>-f18.mod`.  If this
-is needed, Flang's fc1 accepts the option `-module-suffix` to alter the suffix
-used for the module file.
+cannot be in the same directory. This can be solved by adding something
+between the module name and extension, e.g. `<modulename>-f18.mod`.  When
+this is needed, Flang accepts the option `-module-suffix` to alter the suffix.
 
 ## Format
 
-Module files will be Fortran source.
-Declarations of all visible entities will be included, along with private
-entities that they depend on.
-Entity declarations that span multiple statements will be collapsed into
-a single *type-declaration-statement*.
-Executable statements will be omitted.
+Module files are Fortran free form source code.
+(One can, in principle, copy `foo.mod` into `tmp.f90`, recompile it,
+and obtain a matching `foo.mod` file.)
+They include the declarations of all visible locally defined entities along
+with the private entities on which thef depend.
----------------
amsouthwell wrote:

typo: thef

https://github.com/llvm/llvm-project/pull/135107