gazebosim / gazebosim/sdformat

Document required field on spec site

Open
#496 0 comments 1 reaction 0 assignees View on GitHub
documentation
Dominant language
C++
Stars
216
Forks
125
Avg merge
1d 14h
Merged PRs (30d)
14

Description

The [SDF spec documentation](http://sdformat.org/spec) displays a "required" field for each element and attribute. The site shows values like `*` and `+` for the required field. Navigating through that documentation, I didn't find a way to tell what each of these symbols mean. I had to look through the API documentation to find the information:

https://github.com/osrf/sdformat/blob/f59a342469bd9c71bd2dc5b325d777164375b06a/include/sdf/Element.hh#L102-L108

It would be good to display this information on the spec site so users can easily tell what it means. I think it could be placed near the "Tree Key" on the top-right corner.

This issue was motivated by [this question](https://community.gazebosim.org/t/sdformat-spec-required-values/816).

Contributor guide

Open the contributing guide

Research direction

Start with the SDF spec site and compare its displayed required-field symbols with the definitions in include/sdf/Element.hh at lines 102-108. Add an explanation near the “Tree Key” so users can understand `*` and `+`; it is done when the meanings are visible on the spec documentation page.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.