Uploaded image for project: 'WildFly'
  1. WildFly
  2. WFLY-19748

Improve CLI low level operation documentation

XMLWordPrintable

    • Icon: Enhancement Enhancement
    • Resolution: Unresolved
    • Icon: Major Major
    • None
    • None
    • CLI, Documentation
    • None
    • ---
    • ---

      Improve https://docs.wildfly.org/33/Admin_Guide#operation-requests.

      1) 'The formal specification for an operation request is:' section is incomplete.

      a) It doesn't include the syntax for adding request headers (e.g. see https://docs.wildfly.org/33/Admin_Guide#cli-run-as which has

      {roles=[Operator,Auditor]}

      b) It doesn't cover the syntax for parameter values / request header values:
      i) lists, e.g. [a,b]
      ii) maps e.g.

      {a=1,b=true}

      Perhaps this can be done via a quite formal syntax definition a la what is seen in RFC. So more formal than the semi-formal one we have now. Or perhaps we stay semi-formal and add brief explanatory sections. Or both.

      2) After the "/subsystem=logging/root-logger=ROOT:change-root-log-level(level=WARN)" I suggest adding an illustration of an 'add' op, e.g.

      /subsystem=logging/logger=org.wildfly.security:add(level=DEBUG)

      A plain old 'add with various parameters' is a very common op and should be mentioned early on.

      3) https://docs.wildfly.org/33/Admin_Guide#available-operation-types-and-descriptions

      The list of common ops is incomplete.

      The /subsystem=logging:read-operation-names output is out of date.

      4) Maybe....

      "they allow you to read and modify the server configuration as if you were editing the XML configuration files directly" -> "they allow you to read and modify the server configuration directly"

      There isn't a consistent relationship between XML elements and management resources so the "as if you were editing the XML" idea is misleading. I've seen people have a harder time understanding configuring WF if they start from an XML POV and try to make the real config model 'write the xml i want'.

              Unassigned Unassigned
              bstansbe@redhat.com Brian Stansberry
              Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

                Created:
                Updated: