Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-25787

Please list generic topics in rendered SAL API documentation

    XMLWordPrintable

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None

      Description

      The HTML rendering of SAL APIs is very handy, but I have a few requests for further enhancement.

      • By far the biggest issue is that the generic topics are not listed. Unfortunately adding them will be some work. More on this below.
      • I beg you to include a prominent link from the metadata for a given CSC (generated from SALSubsystems.xml) to the API for that CSC. Preferably also include that link in the table. That is arguably the most useful piece of information and it allows CSC docs to link to one obvious place, where a user sees the metadata and can quickly get to the API.
      • Please include a link from the API back to the metadata (that may exist, but I didn't see it).
      • Please consider omitting data for:
        • The Subsystem field. We know what subsystem this is. It's just clutter. (It's also clutter in the XML itself, but that's another issue).
        • Preferably omit the subsystem prefix as well.
        • Deprecated fields, including Version, Author and Explanation
      • Also please consider omitting the following fields, though this is more of a stretch:
        • IDL_Size if it's 1. That means "no limit" (which is confusing) and is the most common case.
        • Count if it's 1. That's by far the common case.

      Regarding how to handle generic topics. The obvious solution is to parse the Generics tag of SALSubsystems, though it's a bit of a nuisance. Another option is to parse the IDL files instead (salobj already has a parser for this, so just call that). This has the one really big disadvantage that it requires the IDL be built before you can generate the HTML. If you can live with that (and it's a big if) you gain some significant advantages:

      • It gives you all the topics. The list is guaranteed to be correct because IDL files are the fundamental information used by OpenSplice (for all languages).
      • It omits the garbage fields; you get the fundamentals: name, type (including if it's an array, and how many elements the array has), description and units.
      • It gives you the actual data type. Several types in the XML are aliases which become the same standard DDS type in the IDL files.
      • The parser already exists and it is the same one used by the sal/kafka producers.

        Attachments

          Issue Links

            Activity

            rowen Russell Owen created issue -
            ecoughlin Eric Coughlin made changes -
            Field Original Value New Value
            Rank Ranked higher
            ecoughlin Eric Coughlin made changes -
            Sprint TSSW Sprint - Jul 6 - Jul 20 [ 1031 ]
            ecoughlin Eric Coughlin made changes -
            Rank Ranked lower
            ecoughlin Eric Coughlin made changes -
            Story Points 2
            ecoughlin Eric Coughlin made changes -
            Status To Do [ 10001 ] In Progress [ 3 ]
            ecoughlin Eric Coughlin made changes -
            Reviewers Russell Owen [ rowen ]
            ecoughlin Eric Coughlin made changes -
            Status In Progress [ 3 ] In Review [ 10004 ]
            rowen Russell Owen made changes -
            Link This issue relates to DM-25846 [ DM-25846 ]
            rowen Russell Owen made changes -
            Link This issue relates to DM-25848 [ DM-25848 ]
            rowen Russell Owen made changes -
            Status In Review [ 10004 ] Reviewed [ 10101 ]
            ecoughlin Eric Coughlin made changes -
            Resolution Done [ 10000 ]
            Status Reviewed [ 10101 ] Done [ 10002 ]
            aclements Andy Clements made changes -
            Epic Link DM-24280 [ 432909 ]

              People

              Assignee:
              ecoughlin Eric Coughlin
              Reporter:
              rowen Russell Owen
              Reviewers:
              Russell Owen
              Watchers:
              Eric Coughlin, Patrick Ingraham, Russell Owen
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  CI Builds

                  No builds found.