[riot-notifications] [RIOT-OS/RIOT] doc: move wiki to Doxygen documentation (second attempt) (#8516)

jia200x notifications at github.com
Mon Apr 9 14:05:15 CEST 2018


>Before, "Modules" basically contained documentation of the logical part of RIOT. Now, hardware to-dos are mixed in there, mixed-in with board-specific defines. While that might be a sensible way to go, I do not see any discussion about it

Basically the idea of this PR was just to move the existing Wiki entries to Doxygen. I fixed some broken links and tables, but the content is exactly the same. I do agree we should find a better way to expose stuff such as hardware TODOs, but that was not the original purpose of this PR.

>there's a "doc.txt" that contains a C commen just so doxygen can parse it. inside the comment is markdown. This is confusing and hacky.

This is a Doxygen limitation. I had the idea of reusing the board.h or periph_conf.h, but not all boards provide one. In any case, I don't see how it could be possible to (easily) use MD files without C style comments. If we assume the board documentation is not meant to be edited by the user (as @aabadie suggested), I think this is not the biggest issue.

>I'm somehow reluctant to ACK this, as while it solves "docs are in one place" and "help developers to keep end-user docs up-to-date", it worsens the overall structure of the documentation, both in the output and in its structure within the repository.

I tend to think this approach could help end users/developers in the short-mid term while we find another solution. Any comments?

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/pull/8516#issuecomment-379728718
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20180409/7189586c/attachment.html>


More information about the notifications mailing list