[flang][docs][nfc] Refine FlangOptionsDocs.td

[awarzynski]

Summary

Currently, FlangOptionsDocs.td doesn't specify ExcludedFlags which
means that in the generated documentation file we expose flags that:

• we don't necessarily want to advertise to our users (e.g. hidden flags), or
• are not supported altogether (e.g. CL options).

This patch defines ExcludeFlags to fix that. The definition of
ExcludeFlags was copied from Clang so that LLVM frontends have
consistent documentation.

It might be a bit counter-intuitive that IncludeFlags alone is not sufficient
here. However, the current logic in ClangOptionDocEmitter.cpp will parse
IncludeFlags and print all options that contains one of the included flags,
as well as their aliases. So, for example, for -fopenmp (which is a
supported Flang option), one would also get /fopenmp (i.e. CL mode
equivalent for -fopenmp). By adding ExcludeFlags,. which make sure
that such aliases are excluded.

I've also taken the liberty and moved FlangOptionsDocs.td. Originally it
was located in Flang's top include directory, but there shouldn't be any
implementation/documentation files there. Instead, I'm moving it to the
flang/docs directory.

[rovka]

This is strange. What does IncludedFlags do, exactly? What happens for instance to FC1Options, do they get included or not?

[DylanFleming-arm]

flang/docs/FlangOptionsDocs.td

36

If you've moved FlangOptionsDocs.td from flang/include/flang/ to flang/docs/, then should this include not be change to "../../clang/include/clang/Driver/Options.td"?

[awarzynski]

I should've mentioned - it might be helpful to see https://reviews.llvm.org/D129864 for context. This patch is a follow-up.

In D130558#3679098, @rovka wrote:

This is strange.

I agree. This is down to how the logic for "including" and "excluding" option flags works (used when e.g. printing --help). It is not particularly flexible. When Flang was introduced, that became quite apparent (we were missing a good mechanism for making sure that clang --help does not contain Fortran options and that flang-new --help does not contain C++ options). This is closely related.

What does IncludedFlags do, exactly?

See here.

What happens for instance to FC1Options, do they get included or not?

They do not get included as they are not listed in includeFlags.

Note that once IncludedFlags is used, only things on the "include" list are ... included. But that includes option aliases, unless ExcludeFlags is used as well (see here).

[awarzynski]

flang/docs/FlangOptionsDocs.td

36

Yes! In fact, this should simply be include "Options.td" and flang/docs/CMakeLists.txt should contain the required include paths. Update coming shortly :)

[awarzynski]

Update include in FlangOptionsDocs.td

[awarzynski]

Fix CMake configuration

[DylanFleming-arm]

LGTM!

[rovka]

In D130558#3679778, @awarzynski wrote:

I should've mentioned - it might be helpful to see https://reviews.llvm.org/D129864 for context. This patch is a follow-up.

In D130558#3679098, @rovka wrote:

This is strange.

I agree. This is down to how the logic for "including" and "excluding" option flags works (used when e.g. printing --help). It is not particularly flexible. When Flang was introduced, that became quite apparent (we were missing a good mechanism for making sure that clang --help does not contain Fortran options and that flang-new --help does not contain C++ options). This is closely related.

What does IncludedFlags do, exactly?

See here.

What happens for instance to FC1Options, do they get included or not?

They do not get included as they are not listed in includeFlags.

Note that once IncludedFlags is used, only things on the "include" list are ... included. But that includes option aliases, unless ExcludeFlags is used as well (see here).

Ok, thanks for the explanation! I think I was probably missing the part about option aliases. Could you update the summary to explain a bit more about why unwanted options were being included? For instance, my expectation would be that irrelevant/unsupported options wouldn't be marked as FlangOptions in the first place, and therefore would not be included by default. I think it's worth clarifying this point in the summary.

[awarzynski]

In D130558#3684754, @rovka wrote:

Could you update the summary to explain a bit more about why unwanted options were being included?

Good idea! How about now?

[rovka]

LGTM, thanks! And sorry to keep you waiting!

flang/docs/CMakeLists.txt

 endif()
 
 function (gen_rst_file_from_td output_file td_option source docs_target)
   if (NOT EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/${source}")
     message(FATAL_ERROR "Cannot find source file: ${source} in ${CMAKE_CURRENT_SOURCE_DIR}")
   endif()
   get_filename_component(TABLEGEN_INCLUDE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/${source}" DIRECTORY)
   list(APPEND LLVM_TABLEGEN_FLAGS "-I${TABLEGEN_INCLUDE_DIR}")
+  list(APPEND LLVM_TABLEGEN_FLAGS "-I${CMAKE_CURRENT_SOURCE_DIR}/../../clang/include/clang/Driver/")
   clang_tablegen(Source/${output_file} ${td_option} SOURCE ${source} TARGET "gen-${output_file}")
   add_dependencies(${docs_target} "gen-${output_file}")
 endfunction()
 
 if (LLVM_ENABLE_SPHINX)
   include(AddSphinxTarget)
   if (SPHINX_FOUND)
     if (${SPHINX_OUTPUT_HTML})
if (${SPHINX_OUTPUT_HTML})
       # Runs a python script prior to HTML generation to prepend a header to FIRLangRef,
       # Without the header, the page is incorrectly formatted, as it assumes the first entry is the page title.
       add_custom_command(TARGET copy-flang-src-docs
         COMMAND "${Python3_EXECUTABLE}"
         ARGS ${CMAKE_CURRENT_BINARY_DIR}/Source/FIR/CreateFIRLangRef.py)
 
       # CLANG_TABLEGEN_EXE variable needs to be set for clang_tablegen to run without error
       set(CLANG_TABLEGEN_EXE clang-tblgen)
-      gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs ../include/flang/FlangOptionsDocs.td docs-flang-html)
+      gen_rst_file_from_td(FlangCommandLineReference.rst -gen-opt-docs FlangOptionsDocs.td docs-flang-html)
     endif()
     if (${SPHINX_OUTPUT_MAN})
       add_sphinx_target(man flang)
     endif()
   endif()
 endif()
 

flang/docs/FlangOptionsDocs.td

 
 Introduction
 ============
 
 }];
 
   string Program = "flang";
 
-  list<string> ExcludedFlags = [];
+  list<string> ExcludedFlags = ["HelpHidden", "NoDriverOption",
+                                "CLOption", "Unsupported", "Ignored"];
   list<string> IncludedFlags = ["FlangOption"];
 
 }
 
 
-include "../../../clang/include/clang/Driver/Options.td"
+include "Options.td"