From 1858d0a186bb52aa194d4961768697e74d60e5c4 Mon Sep 17 00:00:00 2001
From: Gereon Kremer <nafur42@gmail.com>
Date: Wed, 8 Sep 2021 12:14:24 -0700
Subject: [PATCH] Work on comments (#7139)

This PR fixes / improves the comments in the options scripts.
---
 src/options/mkoptions.py | 48 ++++++++++++++++++++--------------------
 1 file changed, 24 insertions(+), 24 deletions(-)

diff --git a/src/options/mkoptions.py b/src/options/mkoptions.py
index d50681eb7..d81d8659c 100644
--- a/src/options/mkoptions.py
+++ b/src/options/mkoptions.py
@@ -11,34 +11,39 @@
 # directory for licensing information.
 # #############################################################################
 ##
-
 """
     Generate option handling code and documentation in one pass. The generated
     files are only written to the destination file if the contents of the file
     has changed (in order to avoid global re-compilation if only single option
     files changed).
 
-    mkoptions.py <tpl-src> <dst> <toml>+
+    mkoptions.py <src> <build> <dst> <toml>+
 
-      <tpl-src> location of all *_template.{cpp,h} files
-      <dst>     destination directory for the generated source code files
+      <src>     base source directory of all toml files
+      <build>   build directory to write the generated sphinx docs
+      <dst>     base destination directory for all generated files
       <toml>+   one or more *_options.toml files
 
 
-    Directory <tpl-src> must contain:
-        - options_template.cpp
-        - options_public_template.cpp
-        - module_template.cpp
-        - module_template.h
+    This script expects the following files (within <src>):
+
+      - <src>/main/options_template.cpp
+      - <src>/options/module_template.cpp
+      - <src>/options/module_template.h
+      - <src>/options/options_public_template.cpp
+      - <src>/options/options_template.cpp
+      - <src>/options/options_template.h
 
-    <toml>+ must be the list of all *.toml option configuration files from
-    the src/options directory.
+    <toml>+ must be the list of all *.toml option configuration files.
 
 
-    The script generates the following files:
-        - <dst>/MODULE_options.h
-        - <dst>/MODULE_options.cpp
-        - <dst>/options.cpp
+    This script generates the following files:
+      - <dst>/main/options.cpp
+      - <dst>/options/<module>_options.cpp (for every toml file)
+      - <dst>/options/<module>_options.h (for every toml file)
+      - <dst>/options/options_public.cpp
+      - <dst>/options/options.cpp
+      - <dst>/options/options.h
 """
 
 import os
@@ -54,10 +59,9 @@ MODULE_ATTR_ALL = MODULE_ATTR_REQ + ['option']
 
 OPTION_ATTR_REQ = ['category', 'type']
 OPTION_ATTR_ALL = OPTION_ATTR_REQ + [
-    'name', 'short', 'long', 'alias',
-    'default', 'alternate', 'mode',
-    'handler', 'predicates', 'includes', 'minimum', 'maximum',
-    'help', 'help_mode'
+    'name', 'short', 'long', 'alias', 'default', 'alternate', 'mode',
+    'handler', 'predicates', 'includes', 'minimum', 'maximum', 'help',
+    'help_mode'
 ]
 
 CATEGORY_VALUES = ['common', 'expert', 'regular', 'undocumented']
@@ -206,11 +210,7 @@ def get_predicates(option):
 
 
 class Module(object):
-    """Options module.
-
-    An options module represents a MODULE_options.toml option configuration
-    file and contains lists of options.
-    """
+    """Represents one options module from one <module>_options.toml file."""
     def __init__(self, d, filename):
         self.__dict__ = {k: d.get(k, None) for k in MODULE_ATTR_ALL}
         self.options = []
-- 
2.30.2