[GitHub] [airflow] kaxil commented on a change in pull request #20567: params concept doc rework

[GitBox <gi...@apache.org>]

kaxil commented on a change in pull request #20567:
URL: https://github.com/apache/airflow/pull/20567#discussion_r776812121



##########
File path: docs/apache-airflow/concepts/params.rst
##########
@@ -18,46 +18,115 @@
 Params
 ======
 
-Params are Airflow's concept of providing runtime configuration to tasks when a DAG gets triggered manually.
-Params are configured while defining the DAG & tasks, that can be altered while doing a manual trigger. The
-ability to update params while triggering a DAG depends on the flag ``core.dag_run_conf_overrides_params``,
-so if that flag is ``False``, params would behave like constants.
+Params are Airflow's way to provide runtime configuration to tasks when a DAG gets triggered manually.
+To use them, initialize your DAG with a dictionary where the keys are strings with each param's name, and the values are ``Param`` objects.
 
-To use them, one can use the ``Param`` class for complex trigger-time validations or simply use primitive types,
-which won't be doing any such validations.
+``Param`` makes use of `json-schema <https://json-schema.org/>`, so one can use the full json-schema specifications mentioned at https://json-schema.org/draft/2020-12/json-schema-validation.html to define the construct of a ``Param`` objects.
+Or, if you want a default value without any validation, you can use literals instead.
 
 .. code-block::
+   :caption a simple DAG with a parameter

Review comment:
       ```suggestion
      :caption: a simple DAG with a parameter
   ```
   
   Check: https://www.sphinx-doc.org/en/1.4.9/markup/code.html#caption-and-name




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org