Re: (patch) Improved documentation and examples of dynamic modules

["Kamil Rytarowski" <n54%gmx.com@localhost>]

Greg Troxel wrote:
> "Kamil Rytarowski" <n54%gmx.com@localhost> writes:
> 
> >> Also, "happy" doesn't seem like a useful name; examples should have
> >> names that suggest the kinds of things they do with respect to the
> >> module system, to guide people choosing which ones to read.
> >
> > Well, I like /dev/happy for Happy Number generator. What would be the
> > better name?
> 
> random_generator?  The point is that someone looking at examples does
> not care what particular generator you are using; the point is about the
> glue code.  It would be fair, arguably better, to have a "random
> generator" that emits sequential numbers. Anything other than module
> glue is a distraction.
> 

For this reason, I took one of the simplest integral sequences and for the
joy of math I would like to stick to it.

It's common to use existing algorithms in basic examples. like Fibonacci
numbers, primes etc.

http://www.home.unix-ag.org/bmeurer/NetBSD/howto-lkm.html uses Fibonacci.
Personally I have a reason to not use it in my patch, I will eventually
unveil why after a month or so. Thanks!

> >> > I like it. Maybe place them in `share/examples/kmodules'?
> >> 
> >> share/examples/sys/modules would be better; kmodules is not the name of
> >> a program in base and would be confusing to someone expecting examples
> >> to be about programs in base.
> >
> > kmodule was inspired by (/usr/share/mk/)bsd.kmodule.mk and it was so
> > natural for me to pick up this name. Maybe share/examples/sys/kmodule?
> 
> I am ok with sys/kmuodules (if this is mis-installed in share/examples).
> 

Therefore share/examples/sys/kmodules (plural form)?

> > I'm improving this single example adding to it 4 additional modules and
> > README. There is no revolution, except moving the original example to a
> > new location.
> 
> So why not just example-foo, example-bar, etc.
> 

Modules named 'example' in a directory 'examples' aren't verbose to me
(is it a pleonasm?).

I'm listing them in README this way:
* hello           - the simplest `hello world' module
* properties      - handle incoming properties during the module load
* happy           - basic implementation of read(9) with happy numbers
* ping            - basic ioctl(9)
* hellolua        - the simplest `hello world' Lua module

The description of what they do is in the README file, not embedded in
their names. I designed it minimal and funny (doing something
quasi-functional) for each case :) It's a matter of taste, but a module dots
with device /dev/dots printing ".\n" would be enough too, but (to me) boring.
With happy numbers people can play a bit with it, easily change the algorithm
to something else (like redefining happy (1) and sad number (4)) and checking
results just for the fun of experimenting with read(4).

> > I'm trying to improve the documentation and add more enlightening examples
> > for newcomers (like myself!).
> 
> > I'm aware of the fact that experienced kernel programmers familiar with
> > NetBSD internals know how to handle all kinds of things, dependencies and
> > for them following 'ab uno disces omnis' (single example just parsing the
> > parameters) is sufficient.
> 
> > Please let it be easier for people starting to hack in the kernel from
> > the modules (people like me) and not assuming they mastered the kernel
> > internals.
> 
> That's great that you are spiffin gup docs and I didn't mean to be
> critical of it.  I just meant that 1) examples belong in the source tree
> 2) example name should be about the kind of function and 3) examples
> should have minimal semantic distraction besides their glue functions.
> So for example a fs transformation module could be gzip or just
> rot13, with just barely enough code to see that it is doing something,
> and a generator could just return 0, 1, 2, 3, 4, etc. enough that you
> can tell it is working.
> 

I understood your argument.

I plan to rediff and send my new patch tomorrow.