Mbed (callback) documentation

[Sissors]

• Type: Enhancement
• Priority: Major

---

This is a two part request / question / feedback:

Specifically I started with my WakeUp library, where I wanted to remove the compilation warnings from the FunctionPointer I used there, so I had to switch to the Callback template. No problem, well except the problem: How? I at least knew I needed the Callback function, but finding documentation for it proved to be impossible. Maybe it is hidden somewhere, but I could not find it. So we just go to the source code, close to 5000 lines of code: https://github.com/ARMmbed/mbed-os/blob/master/platform/Callback.h. Of course not all of them are relevant to what I need, but despite being familiar with both mbed and basic usage of templates, I quickly gave that up. In the end I copied the implementation from the Ticker.h file. Which of course is perfectly fine, but something that is a pretty basic function users would want to add to a library should not require me to search through the source code of mbed on how to implement it.

Next I tried if it compiled, and attaching a member function took me 3 attempts before I had the correct syntax. Also that should be better documented somewhere.

Then the second part: The documentation in general. I cannot find it anymore (and that might tell enough in itself), but I remember what the old "about mbed" page said. Something regarding how it started with how much effort it was for an intern to get started on a simple microcontroller design. Now I realise that the focus of mbed shifted more to the professionals, but is that simply intern also supposed to be able to use it, or should he/she just shift to an Arduino?

This is just one example, but lets say the intern wants to make a PWM signal. The old documentation wasn't perfect (and mainly really outdated with references only to the LPC1768, LPC11u24 and KL25z). But to start with, the new documentation requires quite a bit more searching before you even end up on the PWM page. At which point it starts with: "Use the PwmOut interface to control the frequency and mark-to-space ratio of a digital pulse train."

mark-to-space ratio? Lets just call it dutycyle / pulse width. Next is the API documentation. Well the API, it is just a copy of the .h file. Filled with things where your intern really won't understand what they are about. The Ticker page for example does have an actual API, although there the DEPRECATED warning messages shout through everything. And things like protected member stuff really does not need to be visible on that page, only the public functions.

So I would summarize it as: Please get a first year intern, and let him make a simple setup. And then track how much he can actually use the mbed documentation.

[0xc0170]

cc @AnotherButler @iriark01

[iriark01]

Thank you for the feedback; we'll look at the PWM text. We're in the process of migrating the documentation, which should make finding things easier (and will also fix the copy of the .h file appearing where the doxy should be).

[bulislaw]

@geky callback stuff is a nightmare for me as well ;) Maybe some short guide, examples, central place to copy things from in the Callback.h file would be useful.

@iriark01 I don't think @Sissors meant PWM in specific, finding anything in our docs is difficult. They seem awkwardly structured compared to https://electricimp.com/docs/ or https://docs.particle.io/guide/getting-started/intro/core/ http://www.freertos.org/RTOS.html or even https://simba-os.readthedocs.io/en/latest/ I'm not saying all of these are very good, but seem to be easier to navigate and find what you are looking for.

Also our API docs seem to be broken in many places, not sure it's the web engine or Doxygen itself.

[iriark01]

He was referring to PWM's opening line specifically, which is what I said we'll look into. For the structure, as I said, we're migrating our documentation.

[Sissors]

That was indeed a specific one which was written too complicated, but in general @bulislaw is correct. I don't know exactly what I would say is wrong with them, but they seem to me to be already too hard to find. Yes it is just a few clicks, but I would for starters put the API documentation directly under the documentation menu options (also no idea what my documentation and add documentation there does).

Another completely random example: https://docs.mbed.com/docs/mbed-os-api-reference/en/latest/APIs/tasks/TimeOut/. The protected ones can be removed from the documentation there in my opinion (if you can easily change that setting). However I don't know how you can really improve it while maintaining the automatic link to the source code doxygen (which you should definately do!). However I want to bet that if you go to university, visit the students who just finished the C++ 101 class, and show them that API documentation, not a single one of them is going to have a clue how they should use it.

Now I have another look at it, if you would remove the deprecated parts from there, and have a working Callback documentation, I think you would already have it alot better. That and having it easier accessible.

[ciarmcom]

ARM Internal Ref: MBOTRIAGE-322

[0xc0170]

He was referring to PWM's opening line specifically, which is what I said we'll look into. For the structure, as I said, we're migrating our documentation.

@Sissors Thanks for the feedback. Docs were improved since the issue was created (as you might have noticed we are updating specs for HAL - that should also help !).

I'll close this. If there are still some things outstanding, please update this ticket or create a new one.

cc @AnotherButler