doc: Update and provide high-level doc for all the important modules #4072
Comments
|
Looks good, but I think there is something missing which is key: a point of entry for the high-level documentation, which brings all these elements in the same picture (with coarser granularity if needed). I'm talking about some text and/or graphical elements that would play the role of Section 4 and Figure 1 in http://arxiv.org/pdf/1502.01968v1.pdf for instance. |
|
You mean an update to http://riot-os.org/images/RIOT_network_architecture_dark_updated.png? |
|
What kind of medium should we use for |
|
In the meeting we pretty much decided, that the end result should be, that the high-level docs are in the doxygen documentation (you can add images to doxygen) and the how-tos are well-documented example applications in the |
|
In the meeting (see minutes) we agreed to start with wiki pages, and then in a second phase think about migrating to doxygen. |
|
see #4074 for Wiki. |
|
@emmanuelsearch we did not really agree to that. @kaspar030 was strongly opposed to this. |
|
We can structure the wiki pages the way we want, "by nature" ;) |
|
oops. I did not notice that @kaspar030 was opposing wiki to bootstrap the first phase, but maybe I missed something. Anyways, I am convinced that for the point of entry (the big picture bringing "everything together") we should start with a wiki entry, and link it visible in the wiki home https://github.com/RIOT-OS/RIOT/wiki |
|
rest of the documentation could live elsewhere indeed. No strong opinion about this. |
|
I think we should also have a clear understanding (and "rules") about what goes to the wiki, what goes to the doxygen and what goes to README files, so that we (as in people who work with RIOT and people who are new to RIOT) don't have to search around for a specific bit of information. Here's what I am thinking about:
|
|
Packages are currently documented ad different places afaik: some in the Wiki, some in their respective READMEs. Also: some CPUs, as well as some boards, have READMEs in their directory structure, and some don't. What's up with those? |
|
I think the more goes into Doxygen, the better. How-tos, tutorials, and link collections are great for the Wiki, examples should have a Readme, the rest should go into Doxygen. |
Then where do you draw the line between how-to, tutorial and example? |
|
An example has code in the repository, how-tos and tutorials do not. |
|
Didn't we establish in the meeting, that every how-to should be - or at least be accompanied by - an example? |
|
I don't remember that, but if we did, so what? An example application in the RIOT repository has a README, telling the user what the example does and how to use it. Additional how-tos go to the Wiki. |
@cgundogan and I discussed this over the last few hours, and we basically came to the conclusion, that text-wise an updated version of the text in the doxygen/the RIOT introduction in the wiki (who are basically two versions of the same text) would suffice. For an introductory graphic we came up that would in the end be pretty similar to http://riot-os.org/images/RIOT_network_architecture_dark_preview.png, just more to the point and focusing on the parts that really need more explanation. This is a first preliminary version of that:
|
|
that's indeed the sort of thing I was talking about. Looks good to me. Two comments concerning the pic:
|
Yes of course, after we were pretty detailed on the left 2/3 of the stack we lost focus and sketched out the rest. The one on the right will in the end be pretty similar to one of the GNRC graphics floating around.
I hope to strip the picture down to a more or less editable SVG we can just include into the doxygen's HTML. |
|
Hier a first step example of how it might look like. I'm about to clean up the SVG to get it in a more readable format (that I will then include into the doxygen).
|
|
@authmillenon nice! 👍 |
|
looks good! |
|
See #4090 for the addition to |
|
For the text stuff I started a pad: https://padlite.spline.inf.fu-berlin.de/p/mjtL88j5np |
|
See #4091 how to integrate this. |
|
Hi all! I wanted to support in enhancing the drivers section (adc, pwm, ...) but I got stuck as I don't really know which informations are missing for "externals". So if you already know what you are missing, give me some quick keywords ;-) |
|
This issue can be viewed as more or less deprecated. See #4309 for better overview. |
|
good to know... |
|
Did the above graphic make it into the docs somewhere? I wasn't able to find it. |
|
It has been splited: http://doc.riot-os.org/index.html#structure and http://doc.riot-os.org/group__net__gnrc.html#details |
|
Since the middle part isn't fact in the code base yet we decided against including it. |
|
Ok, thx for explanation. Btw. isn't the MAC layer missing in the GNRC graphic? |
|
The MAC layer can be handled by |
|
(or better said: an extension of it. The current |
|
gnrc_netdev2 doesn't require nomac? But TSCH for example, would still go on top of gnrc_netdev2 IIRC. |
|
No, |
|
I think I still haven't understand how the lower layers are supposed to work in GNRC. |
|
It changed a little with |
As discussed in the meeting from 2015-10-07, we want to update and enhance the current state of the documentation for several of our most important modules. This encompasses high-level documentation of their internals and How-Tos for their internals (as a well documented example). The modules in questions are:
periph) => @thomaseichingerperiph/doc.txt(general documentation) => @PeterKietzmannperiph/adc.hperiph/cpuid.hperiph/dac.hperiph/gpio.hperiph/i2c.hperiph/pwm.hperiph/random.hperiph/rtc.hperiph/rtt.hperiph/spi.hperiph/timer.hperiph/uart.hnetdev2) => @kaspar030gnrc) => @cgundogannet/gnrc.h(general documentation)net/gnrc/ipv6.hetc.net/gnrc/netapi.hnet/gnrc/netdev.hnet/gnrc/netif.hnet/gnrc/netreg.hnet/gnrc/nettype.hnet/gnrc/pktbuf.hnet/gnrc/pkt.hnet/gnrc/sixlowpan.hetc.net/gnrc/udp.hconn) => @authmillenonnet/conn.h(general documentation)net/conn/ip.hnet/conn/tcp.hnet/conn/udp.hxtimer=> @kaspar030saul=> @haukepetersenThe assignments to the modules are people that to my opinion would be best suited to write the documentation. If you don't agree, either change it or let's discuss it. An assignment could also be interpreted that you can sub-delegate the tasks to other people.
The text was updated successfully, but these errors were encountered: