open-simulation-interface icon indicating copy to clipboard operation
open-simulation-interface copied to clipboard

Documentation of some top-level messages is missing

Open TimmRuppert opened this issue 1 year ago • 1 comments

Describe the bug

According to this page TrafficCommandUpdate and HostVehicleData are top-level messages but they are missing a sub chapter in "2.2.2 Top-level interfaces"

Describe how to reproduce the bug

Steps to reproduce the behavior:

  1. Go to https://opensimulationinterface.github.io/osi-antora-generator/asamosi/V3.7.0/interface/architecture/architecture_overview.html
  2. Compare the first paragraph with the chapters under 2.2.2

Describe the expected behavior

A "Top-level interfaces" chapters should include all top-level messages.

Show some screenshots

image

Additional context

When adding those chapters it would also recommend doing the following:

  • Simplify the sentence about the history of when which message/interface came with which version.
  • Precise usage of interface and message or just use one of them. E.g. the chapter is named "2.2.2 Top-level interfaces" but the subtext for such an interface starts with "GroundTruth messages describes..." or "SensorData messages imitate.."
    • Imho I would replace most occurrences of the word "interface" with "message" (some might argue they are two different things but I don't think this is more important than understanding the documentation a bit better)

I have never used TrafficCommandUpdate and thus might not be the expert to provide a quick chapter about it. In case there is nobody suitable available to fix this issue I could provide a PR where I simply copy the text of the class description

TimmRuppert avatar Oct 21 '24 10:10 TimmRuppert

I am no expert regarding OSI content, so I will refrain from discussion the pros and cons of using messages vs. interfaces, particularly with protobuf (where, to my understanding, you define messages, not interfaces). For now, I left both message(s) and interface(s) as is. I was involved in this project to update the document generation process and introduce build tool improvements as well as an automated release pipeline. Content-related changes should be decided by the group and then, if necessary, fixed throughout the whole document (possibly through this or another branch/PR).

Regarding the missing sections and files: I added new pages and used content from the interface specification. I also took the liberty of adding links to the (doxygen) reference pages since this should benefit the reader if they wanted to learn more details than just the broad overview.

philipwindecker avatar Oct 22 '24 14:10 philipwindecker