Suggestions for documentation - please comment

Firmware/software/electronics/mechanics
Post Reply
bot-motion
Beginner
Posts: 7
Joined: Mon Mar 08, 2021 8:16 pm
Location: Frankfurt, Germany
Contact:

Suggestions for documentation - please comment

Post by bot-motion »

I have two questions w/ regard to documentation:

* I started drawing graphs of how the program flow works in the firmware. It helps me think about how to implement my own project(s). I'm a noob in embedded programming and only a hobbyist - so I can't guarantee those drawings would be useful for anyone even if improved. Example is attached. Would this be useful/could this be integrated into documentation somewhere? Any hints what I should do to make it more useful?

[I made other sketches e.g. tracing the way of information for the multiranger deck from the sensor to the log/the cflib. I'm compiling a list of all the tasks ususally created, and how the system initializes]

* Is it still of interest to have a doxygen documentation? I saw that some comments are still such that it's possible to generate something, but there's no config file for doxy.
Attachments
firmware_overview.png
bot-motion
Beginner
Posts: 7
Joined: Mon Mar 08, 2021 8:16 pm
Location: Frankfurt, Germany
Contact:

Re: Suggestions for documentation - please comment

Post by bot-motion »

I started playing with doxygen to figure out how it might generate sth that helps a beginner understand structure rather than detail.

The trick could be to describe

* what you can do
* how information flows

See the attached screenshot for a more concrete example: say, I want to understand how to use sensor readings in my on app()-layer. I start looking, and lo-and-behold there is multiranger.c. But wait, that is what my deck is called, but that's not where the data is (for my consuming app). But I find a hint that I should use range.c.

Does that make sense?
Attachments
why-doxy.PNG
kristoffer
Bitcraze
Posts: 630
Joined: Tue Jun 30, 2015 7:47 am

Re: Suggestions for documentation - please comment

Post by kristoffer »

Hi!

We think it could be interesting to add auto generated docs from the code, but have not had the time to do it. I did a quick test with doxygen but ran into some issues that I did not find a solution to.
The problem I found is when integrating the content into our main web site. Currently we build the documentation in each repository (located in the /docs folder) and massage it to fit into the web. For instance, you can find the documentation for the Crazyflie firmware (https://github.com/bitcraze/crazyflie-f ... aster/docs) in https://www.bitcraze.io/documentation/r ... re/master/. Documentation for various release tags are also available in a similar way.
There are a bunch of repos that we handle the docs for in this way.

We were hoping to be able to get the auto generated docs added in a similar way, but this is where I ran into some problems. I did not manage to generate HTML that could be added into our web as a sub tree without too much hacking around. The main problem seemed to be the menu to the left if I remember correctly.

It might be possible to generate code that would work but it is beyond my knowledge. It would be awesome if you know how to do it!

For the more human generated docs, there are two main areas: the repo docs mentioned above and for documentation spanning multiple repos (probably what you are looking for mainly) the tutorials section on the web https://www.bitcraze.io/documentation/tutorials/

If you want to contribute you are more than welcome!
bot-motion
Beginner
Posts: 7
Joined: Mon Mar 08, 2021 8:16 pm
Location: Frankfurt, Germany
Contact:

Re: Suggestions for documentation - please comment

Post by bot-motion »

Hi,

thanks for the reply!

I read about your goal to have the doc automagically added to the website/github, and I'd guess that's difficult indeed. I would think that people engaging with the firmware have at least some experience, so if we add a 'doc' step to the makefile/'build' process that contains a doxygen call, provide the doxy config file, and maybe add a short explanation to the main README - then most people would be able to benefit without you having to fiddle around with the website.

I think it's kind of an opportunity if I at least add some doxygen documentation as long as I'm still looking at it wondering about many things - I suppose the more one knows the more difficult it gets to write doc for 'mass consumption'.

I'll add some more and open a pull request, and you can decide what you want to take over.
kristoffer
Bitcraze
Posts: 630
Joined: Tue Jun 30, 2015 7:47 am

Re: Suggestions for documentation - please comment

Post by kristoffer »

I'll take a look at the pull request. Let's continue the conversation there

Thanks!
Post Reply