[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.
 
 ### Header
 
-There will be a header containing extra information that cannot be expressed
-in Fortran. This will take the form of a comment or directive
-at the beginning of the file.
-
-If it's a comment, the module file reader would have to strip it out and
-perform *ad hoc* parsing on it. If it's a directive the compiler could
-parse it like other directives as part of the grammar.
-Processing the header before parsing might result in better error messages
-when the `.mod` file is invalid.
-
-Regardless of whether the header is a comment or directive we can use the
-same string to introduce it: `!mod$`.
+Module files begin with a UTF-8 byte order mark and a few lines of
+Fortran comments.
+(Pro tip: use `dd if=foo.mod bs=1 skip=3 2>/dev/null` to skip the byte order
+mark and dump the rest of the module.)
+The first comment begins `!mod$` and contains a version number
+and hash code.
+Further `!need$` comments contain the names and hash codes of other modules
+on which this module depends, and whether those modules are intrinsic
+or not to Fortran.
 
-Information in the header:
-- Magic string to confirm it is an f18 `.mod` file
-- Version information: to indicate the version of the file format, in case it changes,
-  and the version of the compiler that wrote the file, for diagnostics.
-- Checksum of the body of the current file
-- Modules we depend on and the checksum of their module file when the current
-  module file is created
-- The source file that produced the `.mod` file? This could be used in error messages.
+The header comments do not contain timestamps or original source file paths.
 
 ### Body
 
-The body will consist of minimal Fortran source for the required declarations.
-The order will match the order they first appeared in the source.
-
-Some normalization will take place:
-- extraneous spaces will be removed
-- implicit types will be made explicit
-- attributes will be written in a consistent order
-- entity declarations will be combined into a single declaration
-- function return types specified in a *prefix-spec* will be replaced by
-  an entity declaration
-- etc.
+The body comprises minimal Fortran source for the required declarations.
+Their order generally matches the order they appeared in the original
+source code for the module.
+All types are explicit, and all non-character literal constants are
+marked with explicit kind values.
+
+Declarations of objects, interfaces, types, and other entities are
+regenerated from the compiler's symbol table.
+So entity declarations that spanned multiple statements in the source
+program are effectivel collapsed into a single *type-declaration-statement*.
----------------
amsouthwell wrote:

typo: effectivel

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