search

Open-CMSIS-Pack / Open-CMSIS-Pack-Spec

Common Microcontroller Software Interface Standard - Pack(age) based distribution system
https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/
Apache License 2.0
50 stars 19 forks source link

Limit size of "description" attribute or element #275

Closed ReinhardKeil closed 3 months ago

ReinhardKeil commented 5 months ago

Problem

The Open-CMSIS-Pack spec uses the term "brief description", however there is no guidance of a reasonable size or any limit enforcement.

Tools that show such descriptions have however practical limitations (see below)

image

Suggestion

FelixWang47831 commented 5 months ago

Hi @ReinhardKeil For long description, I find it will show multiple lines for description information. It holds enough characters and is easy to read. So why not have a multi-line display based on 50 or 60 characters to a line? For example: image I think it's more friendly for user to get enough information about the project from Pack Installer. And 256 character limitation could be a hard-to-find limitation for the average developer.

ReinhardKeil commented 5 months ago

@FelixWang47831 it's about usability. We want to show a "table of content". There is also a way to link a documentation (could be local or a web URL) that should provide more information. The example below shows a README.md file that could use the formatting features of Markdown (shown nicely in VS Code).

    <example name="Blinky" doc="README.md" folder="Projects/Blinky">
      <description>CMSIS-RTOS2 Blinky example with VIO</description>
      <board name="B-L475E-IOT01A" vendor="STMicroelectronics"/>

In your case the title could be "Shows usage of CMSIS-Driver Ethernet (transmits frames and prints received frames)."

Note: the link to a document is not yet implemented, but IMHO has higher priority. The document could be also shown once the example is imported into the IDE. It could be part of the project.

ReinhardKeil commented 5 months ago

OK to implement the proposed limitations.

jkrech commented 4 months ago

Raised packchk issue: https://github.com/Open-CMSIS-Pack/devtools/issues/1324 ToDo: update documentation with recommendation for all description related elements and attributes.

jkrech commented 3 months ago

Documentation got updated. Packchk update is tracked in above mentioned issue.

https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_package_pg.html#element_package https://open-cmsis-pack.github.io/Open-CMSIS-Pack-Spec/main/html/pdsc_examples_pg.html#element_example