ARMmbed/mbed-os-5-docs

Bad link and bad code on https://os.mbed.com/docs/mbed-os/v6.15/apis/platform-concepts.html

supcik opened this issue · 2 comments

supcik commented

Docs issue template

Page link

https://os.mbed.com/docs/mbed-os/v6.15/apis/platform-concepts.html

Expected to find...

On this page, there is a link "Importance of State" pointing to a wrong page ("platform.html#the-importance-of-state" instead of "platform-concepts.html#the-importance-of-state"

In the main.cpp code (https://github.com/ARMmbed/mbed-os-snippet-PlatfromOverview_Callbacks/blob/v6.15/main.cpp), the echo function reads and writes a char, but the size argument (sizeof(c)) returns the size of the pointer (4 on a 32 bit system) instead of 1.

Found

  • Link to wrong page
  • Error in code

Remark

I tried to find the corresponding pages in github, but I don't understand how URL are mapped to markdown documents.

For example :

  • The page with the title "Platform overview" is at the URL ".../apis/platform-concepts.html" and the markdown file seems to be "docs/api/platform/platform.md"
  • The page with the title "Platform APIs" is at the URL ".../apis/platform.html" and the markdown seems to be "docs/api/platform/platform_list.md"

Can you please explain the rules between the title, the URL and the ".md" file?

Thank you very much in advance.

0xc0170 commented

To the remark:

The tree structure is defined https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs.json where you can find .md files (this is my understanding. Most of the time I check here or just search for the section in the docs folder and edit the markdown file).

I assume docs/api/platform/platform.md needs fixing - the url update, is that it?

ChrisGooch-Arm commented

I have fixed the broken link and created a PR - #1497. Thanks for spotting.

The URL structure of the docs project is driven by the docs.json file as mentioned above, and unfortunately that has led to some differences between the filenames/structure of the project source and the website URLs / structure which may not always be obvious without reference to the json file.

In terms of the code example fix - presumably the code should be using strlen(), not sizeof()?