Ensure that each config item has at least a one line description

[MetRonnie]

In the workflow and global config reference docs

[wxtim]

>>> from cylc.flow.cfgspec.workflow import SPEC
>>> from cylc.flow.cfgspec.globalcfg import SPEC as GSPEC
>>> print('\n - [ ] '.join([repr(i[1]).replace('<', '&lt;') for i in SPEC.walk() if not i[1].desc]))
>>> print('\n - [ ] '.join([repr(i[1]).replace('<', '&lt;') for i in GSPEC.walk() if not i[1].desc]))

[datamel]

@wxtim Something like:

diff --git a/cylc/flow/cfgspec/globalcfg.py b/cylc/flow/cfgspec/globalcfg.py
--- a/cylc/flow/cfgspec/globalcfg.py
+++ b/cylc/flow/cfgspec/globalcfg.py
@@ -792,7 +792,10 @@ with Conf('global.cylc', desc='''
 
             .. versionadded:: 8.0.0
         """):
-            with Conf('<install target>'):
+            with Conf('<install target>',
+                      desc="""
+                Install target where directories to be symlinked are located.
+            """):
                 Conf('run', VDR.V_STRING, None, desc="""
                     Alternative location for the run dir.

[wxtim]

Only flow.cylc[scheduler][events] left...

[MetRonnie]

Most of the global.cylc[platforms][<platform name>]retrieve job logs * do not have a description (even if they are relatively self-explanatory)

[wxtim]

Most of the global.cylc[platforms][<platform name>]retrieve job logs * do not have a description (even if they are relatively self-explanatory)

really? Not what I'm seeing!

[MetRonnie]

They just have the versionchanged admonition (apart from retrieve job logs command)

[wxtim]

They just have the versionchanged admonition (apart from retrieve job logs command)

Legit and well checked - will fix on my return from lunch, although possibly out of scope for this ticket because there is some info there, it's just not terribly enlightning.

[hjoliver]

Hold off @wxtim - I'm just about to post a PR myself.

(I also missed these items at first, because they do have a description, just not one that explains what they mean).

[oliver-sanders]

Issue still under progress:

some flow.cylc config item descriptions ... coming shortly

-- #4997 (comment)