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

[FSDEV] Update the STM32 documentation #2676

Merged
merged 5 commits into from
Jun 21, 2024

Conversation

Okarss
Copy link
Contributor

@Okarss Okarss commented Jun 14, 2024

Seeing the upcoming #2672, also added U535/U545 as supported.

@Okarss Okarss marked this pull request as draft June 14, 2024 18:54
@Okarss
Copy link
Contributor Author

Okarss commented Jun 15, 2024

Looking more into supported.rst ...

| G4                    | ✔      | ✖    | ✖         | stm32_fsdev       |
| WBx5                  | ✔      |      |           | stm32_fsdev       |

The hardware of both are of a full-speed USB device type. It seems that there is a confusion of what exactly the ✖ and empty box means. Currently both are used for two options:

  • Not supported by hardware.
  • Hardware capable, but not supported by software implementation.

To improve the clarity I propose changing the meaning and explanation to this:

  • Empty - Not supported by hardware.
  • ✖ - Hardware capable, but not supported by software implementation.

That way, if there is any symbol present, it means that the hardware is capable of that particular feature and the symbol itself just shows the status of the software implementation. To me such an approach seems to be more useful and consistent. If the main developers agree to such a change, I could at least update this for STM32 devices and probably some other.

Any comments?

@hathach
Copy link
Owner

hathach commented Jun 17, 2024

actually, I don't manage the docs well enough. The idea is

  • ✔: tested and worked
  • ✖: hw is not supported
  • (empty): no information, maintainer just forgot or have no idea.

If you are user WBx5 is FS device only, please make a pr to update it.

@Okarss Okarss marked this pull request as ready for review June 18, 2024 09:33
@Okarss
Copy link
Contributor Author

Okarss commented Jun 18, 2024

Also slightly updated the table legend. As there are no functional changes, despite the failing hardware test, this PR is ready to go.

Copy link
Owner

@hathach hathach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

all look good, though there is a missing table format in the comment, which cause github not rendering table correcting.

docs/reference/supported.rst Outdated Show resolved Hide resolved
@HiFiPhile
Copy link
Collaborator

Table looks good, somehow legend is not shown
image

@hathach
Copy link
Owner

hathach commented Jun 21, 2024

Table looks good, somehow legend is not shown image

[ ] is an syntax, I think we need to escape it, or just use (empty) or simply "empty"/empty instead

@Okarss
Copy link
Contributor Author

Okarss commented Jun 21, 2024

Sorry for the blunder! I wasn't familiar with RST syntax and didn't pay enough attention to that smaller table. Now learned a bit about the syntax, used this online editor and it seems that the latest commit is finally correct.

Copy link
Owner

@hathach hathach left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

perfect, thank you. No problem with the rst, I am not familliar with it as well. I normally prefer markdown, but rst generated nice docs page/site.

@hathach hathach merged commit 044f4d1 into hathach:master Jun 21, 2024
76 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants