manual page comments...

[Poul-Henning Kamp]

I sat down with a printout of the manual pages and a pencil, here
are my comments.

Overall: great stuff, thanks a lot!

I'd like to suggest that symmetric operations gets merged,
for instance g_new_consumer() and g_destroy_consumer etc.

We should probably also tie all these into a revised version
of geom(4).

About examples:  I wonder if a geom_example page with a heavily
commented "null" class might be a better idea than a lot of skeleton
examples in the various pages.

DECLARE_GEOM_CLASS

	Mention that it works both for compiled in and KLD'ed classes.

	Mention that on activation all preexisting providers are offered
	for tasting.

	We to document the member functions as well, and I wonder
	if they should be described on this page, on a "g_class"
	page or on one dedicated page for each.

	->destroy_geom is also called at other times, in particular
	as a result of the user asking for it to happen.

	In the g_class initialization, please mention that people
	MUST use C99 initialization (like the example) so we can
	change the struct later on (this is important!).

g_attach

	merge with g_detach page ?

	"From now on a geom ... of another class" is not really correct
	and rather unclear.

	Mention that access counts are necessary before actual I/O can
	happen.

g_bio
	remove mention of bio_bcount, bio_resid, they are, and should
	not be used in GEOM.

	bio_driver[12]   s/$/(ie: the provider)/
	bio_caller[12]   s/$/(ie: the consumer)/

	bio_completed	Number of bytes completed, but they may not be
			completed from the front of the request.

	bio_from, bio_to, bio_children, bio_inbed, bio_parent:
			mention that they are normally read-only for
			a class.

	example:  Technically it could be done without a softc, and
		that might be worth a comment, but please keep the
		softc in the example since it shows how to derive it
		from the bio.

	/*
	 * Could be:
	 * g_io_request(cbp, LIST_FIRST(&bp->bio_to->geom->consumers));
	 */
	g_io_requst(cbp, sc->ex_consumer);
	
g_destroy_consumer:

	merge with g_new_consumer ?	

	s/Typically t/T/

g_destroy_geom:

	merge with g_new_geomf ?

g_destroy_provider

	merge with g_new_providerf ?

	s/A topology lock/The topology lock/  (May apply other files as well)

g_error_provider

	maybe merge with g_new_providerf

	s/sectorsize, the function/sectorsize and other initialization, the function/

g_new_geomf

	We need to document the member functions, either here, in a "g_geom"
	page or one each their own pages.

	s/geom you need to/geom you must/  (twice)

g_new_providerf

	s/an undefined situation/programmer error/

g_post_event

	merge with g_cancel_event ?

	needs better example.

	mention that events are good for avoiding running out of stack
	and for lock-barrier transitions.

g_provider_by_name

	you must hold topology.  The reason this is not enforced with
	KASSERT is the clone routine in geom_dev which cannot (this is
	a problem I need to fix).

g_read_data, g_write_data

	merge

	s/more than or equal to 512/a multiple of the sectorsize for the provider/

g_waitfor_event

	/can not be called recusively/can not be called from an event/
		(we should enforce this with KASSERT if we can)

	better example.

g_wither_geom

	explain that this is an automatic "garbage collect" to avoid
	duplicated code in all classes.  Mention that the softc should
	be disposed off and NULL'ed before calling this functions.

	Mention that withering a geom is not enough to ensure you can
	unload a class.
	


-- 
Poul-Henning Kamp       | UNIX since Zilog Zeus 3.20
phk at FreeBSD.ORG         | TCP/IP since RFC 956
FreeBSD committer       | BSD since 4.3-tahoe
Never attribute to malice what can adequately be explained by incompetence.