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.
Suggestions for documentation - please comment
-
- Beginner
- Posts: 7
- Joined: Mon Mar 08, 2021 8:16 pm
- Location: Frankfurt, Germany
- Contact:
-
- Beginner
- Posts: 7
- Joined: Mon Mar 08, 2021 8:16 pm
- Location: Frankfurt, Germany
- Contact:
Re: Suggestions for documentation - please comment
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?
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?
-
- Bitcraze
- Posts: 630
- Joined: Tue Jun 30, 2015 7:47 am
Re: Suggestions for documentation - please comment
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!
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!
-
- Beginner
- Posts: 7
- Joined: Mon Mar 08, 2021 8:16 pm
- Location: Frankfurt, Germany
- Contact:
Re: Suggestions for documentation - please comment
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.
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.
-
- Bitcraze
- Posts: 630
- Joined: Tue Jun 30, 2015 7:47 am
Re: Suggestions for documentation - please comment
I'll take a look at the pull request. Let's continue the conversation there
Thanks!
Thanks!