Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation of some top-level messages is missing #836

Closed
TimmRuppert opened this issue Oct 21, 2024 · 1 comment · Fixed by #838
Closed

Documentation of some top-level messages is missing #836

TimmRuppert opened this issue Oct 21, 2024 · 1 comment · Fixed by #838
Assignees
Labels
Documentation Everything which impacts the quality of the documentation and guidelines. ReadyForCCBReview Indicates that this MR is ready for a final review and merge by the CCB.

Comments

@TimmRuppert
Copy link

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 TimmRuppert added the Documentation Everything which impacts the quality of the documentation and guidelines. label Oct 21, 2024
@TimmRuppert TimmRuppert changed the title Documentation of some top-level messages is missing. Documentation of some top-level messages is missing Oct 21, 2024
philipwindecker added a commit that referenced this issue Oct 22, 2024
Added links to interface specification pages.

Signed-off-by: Philip WINDECKER (AVENYR GmbH) <philip.windecker@avenyr.de>
@philipwindecker
Copy link
Contributor

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 philipwindecker linked a pull request Oct 22, 2024 that will close this issue
6 tasks
@philipwindecker philipwindecker added the ReadyForCCBReview Indicates that this MR is ready for a final review and merge by the CCB. label Oct 23, 2024
jdsika pushed a commit that referenced this issue Nov 14, 2024
* Issue #836: Added links to interface specification pages.
----------
Signed-off-by: Philip WINDECKER (AVENYR GmbH) <philip.windecker@avenyr.de>
Co-authored-by: Carlo van Driesten <carlo.van-driesten@bmw.de>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Everything which impacts the quality of the documentation and guidelines. ReadyForCCBReview Indicates that this MR is ready for a final review and merge by the CCB.
Projects
None yet
2 participants