Build profile docs change related to sleep #140
Conversation
docs/dev_tools/build_profiles.md
Outdated
| @@ -10,6 +10,7 @@ mbed OS 5 supports three primary build profiles: *develop*, *debug* and *release | |||
| * Largest and slowest profile. | |||
| * Full error information. For example, asserts have file name and line number. | |||
| * Easy to step through code with a debugger. | |||
| * Sleep is disabled. | |||
There was a problem hiding this comment.
To eliminate passive voice, I recommend changing this to "Disabled sleep" or "Disabled sleep mode". Would that keep the same meaning?
|
Good point, will update. |
|
There is probably a way to rejigger things so you can avoid repeating yourself. |
|
I think it's cleaner to repeat small amount of text than to make some 'common' options with exclusions. |
|
Yes, a repeating small amount is much more readable than a common section with exclusions. However, the issues listed here for when sleep is enabled sound like good candidates for a known issues document. This location is probably not the first place a user would expect to find these known issues, although it may be handy to link to them from here. It's also probably difficult to keep these caveats up to date as they aren't as visible as a known issues document which would get reviewed on every release. (I'm assuming that eventually these sleep issues will get fixed.) |
|
I agree, unfortunately our docs are not necessarily very well structured or clear to find things in. https://docs.mbed.com/docs/mbed-os-handbook/en/latest/ |
|
As an outsider, I'd look for known issues in the GitHub issue tracker or in a dedicated release notes document. Anyway, making sure these issues are in the GitHub issue tracker or in release notes is not really something for this PR to deal with. |
docs/dev_tools/build_profiles.md
Outdated
| @@ -5,11 +5,15 @@ mbed OS 5 supports three primary build profiles: *develop*, *debug* and *release | |||
| * Small and fast code. | |||
| * Full error information. For example, asserts have file name and line number. | |||
| * Hard to follow code flow when using a debugger. | |||
| * Chip is put to sleep when going idle: | |||
There was a problem hiding this comment.
Query: Could we change this to "Chip goes to sleep we idle" and keep the meaning? I would like to avoid the passive voice in "is put to sleep".
There was a problem hiding this comment.
"The RTOS idle task puts the chip to sleep." is accurate, but maybe too detailed.
"The chip sleeps when idle." is accurate as well.
|
@geky @theotherjimmy Should I merge this? The instructions say to merge it after we merge ARMmbed/mbed-os#4097, but I see ARMmbed/mbed-os#4200 reverts that. |
|
I would wait, it does look like the revert will go through, but I suspect a slightly revised pr will be merged later. |
|
@geky Thanks. I'll do that. |
|
@geky Should I merge this yet or still wait? |
|
The revert PR was closed ARMmbed/mbed-os#4200 I think that should be merged to reflect what's going on in the code. Then we should update the docs again when/if it changes. |
Apply changes from merged PR #140
This change will be needed when ARMmbed/mbed-os#4097 is merged.