[riot-devel] RIOT examples

Oleg Hahm oliver.hahm at inria.fr
Fri Aug 14 14:54:50 CEST 2015


Hey Kaspar!

Thanks for initiative.

> listening to incoming feedback about RIOT, it seems that while we get a
> lot of praise for our well-documented API, it seems that people are
> missing more high-level concept documentation and more to-the-point
> examples on how to do things in RIOT.

Agreed.

> I propose to extend these with very simple, condensed example
> "applications", where each example just shows how to do a simple task,
> like "set up a periodic timer".

I think one reason against these applications for now was that all
applications have to be updated once an API change happens (which has been the
case in RIOT rather often). Since we're hoping to reaching a more stable API
soon, this argument may have less weight now.
  
> Initially I thought about creating a directory structure that corresponds to
> either the file system hierarchy or the doxygen group hierarchy, as in:
> 
> "examples/sys/xtimer/xtimer_periodic"
> 
> or
> 
> "examples/sys/timers/timer_periodic"
> 
> But maybe we can even live with one examples directory holding all examples,
> as that makes finding them very easy.

I think I would also prefer a flat hierarchy and keep it simple.
  
> Looking at our doxygen, I'd propose to put examples into an "examples"
> subgroup for each group that actually has examples.

+100

(Is it the first time I hear a pro-documentation proposal from your side? ;-))
  
> Do you think more condensed examples would be useful?

What exactly do you mean by "condensed"?
  
> Do you have an opinion on how to structure them?

Not really, I was only wondering if we may limit build tests for these
examples to native, to save load on the CI server.

Cheers,
Oleg
-- 
panic("kmem_cache_init(): Offsets are wrong - I've been messed with!");
        linux-2.2.16/mm/slab.c
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: not available
URL: <http://lists.riot-os.org/pipermail/devel/attachments/20150814/ae3a061b/attachment.sig>


More information about the devel mailing list