NetBSD Problem Report #32430

From imago@13thmonkey.org  Sun Jan  1 23:43:53 2006
Return-Path: <imago@13thmonkey.org>
Received: from rangerover.13thmonkey.org (internetplanet.demon.nl [82.161.161.224])
	by narn.netbsd.org (Postfix) with ESMTP id 01C2D63B942
	for <gnats-bugs@gnats.NetBSD.org>; Sun,  1 Jan 2006 23:43:52 +0000 (UTC)
Message-Id: <20060101234348.995E755F0@rangerover.13thmonkey.org>
Date: Mon,  2 Jan 2006 00:43:48 +0100 (CET)
From: reinoud@NetBSD.org
Reply-To: reinoud@NetBSD.org
To: gnats-bugs@netbsd.org
Subject: genfs lacking documentation
X-Send-Pr-Version: 3.95

>Number:         32430
>Category:       kern
>Synopsis:       There is no documentation on genfs nor its gop's
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    kern-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Mon Jan 02 07:16:02 +0000 2006
>Last-Modified:  Sat Jun 11 11:40:02 +0000 2011
>Originator:     Reinoud Zandijk
>Release:        NetBSD 2.99.16
>Organization:
NetBSD

>Environment:


System: NetBSD rangerover 2.99.16 NetBSD 2.99.16 (GENERIC) #1: Tue Feb 22 20:57:13 CET 2005 imago@heethoofdje.kasbah:/usr/sources/cvs.netbsd.org/src/sys/arch/sparc/compile/obj/GENERIC sparc
Architecture: sparc
Machine: sparc
>Description:
There is no documentation on src/sys/miscfs/genfs. There is no description 
of how to interact with it nor what the gop calls do.


>How-To-Repeat:
-

>Fix:
Write manpage.


>Audit-Trail:
From: Julian Fagir <gnrp@komkon2.de>
To: gnats-bugs@netbsd.org
Cc: 
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 11:12:45 +0200

 Hi,

 recently we had a discussion in the IRCNet #netbsd about that topic.
 After having a short look, we created a stub for genfs, layerfs, fifofs and
 specfs by copying their description from the NetBSD internals guide and
 adding some references.

 It is intended to be used as genfs(9), and also linked to layerfs(9),
 fifofs(9), specfs(9).

 I uploaded it to http://komkon2.de/genfs.9

 Regards, Julian

From: Reinoud Zandijk <reinoud@NetBSD.org>
To: gnats-bugs@NetBSD.org
Cc: kern-bug-people@netbsd.org, gnats-admin@netbsd.org,
	netbsd-bugs@netbsd.org
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 12:27:33 +0200

 On Sat, Jun 11, 2011 at 09:15:06AM +0000, Julian Fagir wrote:
 >  recently we had a discussion in the IRCNet #netbsd about that topic.
 >  After having a short look, we created a stub for genfs, layerfs, fifofs and
 >  specfs by copying their description from the NetBSD internals guide and
 >  adding some references.
 >  
 >  It is intended to be used as genfs(9), and also linked to layerfs(9),
 >  fifofs(9), specfs(9).

 Thanks for the start. What i was targeting in the PR however was a description
 of the various generic FS functions genfs provides and more important its
 callbacks.

 I think the stub should be more seen as a genfs(0), layerfs(0), specfs(0),
 fifofs(0). Still a nice thing to add :) Even if its just marked as a stub.
 People seeing references to them at least have a way of knowing what it is all
 about.

 The genfs(9) could then deal with the semantics of the genfs and its callbacks
 and their semantics i.e. when are they called and why. The specfs(9) could
 then deal with the special issues around special files etc.

 With regards,
 Reinoud

From: Jukka Ruohonen <jruohonen@iki.fi>
To: gnats-bugs@NetBSD.org
Cc: reinoud@NetBSD.org
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 13:48:36 +0300

 On Sat, Jun 11, 2011 at 10:30:07AM +0000, Reinoud Zandijk wrote:
 >  I think the stub should be more seen as a genfs(0), layerfs(0), specfs(0),
 >  fifofs(0). Still a nice thing to add :) Even if its just marked as a stub.
 >  People seeing references to them at least have a way of knowing what it is all
 >  about.

 There is no "section zero". Since the page contains the CODE REFERENCES
 section, and references to various section 9 pages, section 9 seems right.
 Otherwise, section 7 could be appropriate.

 But.

 Clearly this is unfinished. I don't see much value with stubs like this.

      "The genfs subsystem implements generic filesystem operations to be
       shared across different filesystems".

 This comes close to "null-documentation". Note that the issue has been
 discussed previously [1].

 - Jukka.

 [1] http://mail-index.netbsd.org/current-users/2010/05/13/msg013353.html

From: Julian Fagir <gnrp@komkon2.de>
To: gnats-bugs@NetBSD.org
Cc: 
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 13:21:57 +0200

 Hi,

 >  Clearly this is unfinished. I don't see much value with stubs like this.
 >  
 >       "The genfs subsystem implements generic filesystem operations to be
 >        shared across different filesystems".
 >
 >  This comes close to "null-documentation". Note that the issue has been
 >  discussed previously [1].
 Ah, I didn't know that, ok.
 Yes, it is unfinished. The thought about making a stub came up when I wanted
 to know what genfs is for, but found nothing in the online documentation.
 Only analysing the code a bit and eventually having it seen in the NetBSD
 Internals Guide turned out what it really is. Having a manpage for faster
 lookup would be nice.
 There is actually no more documentation about these issues anywhere than
 this manpage/in the NetBSD Internals.

 I agree this does not have a great value, but at least you find documentation
 somewhere in the online documentation of what it is about.
 The question seems to be rather if you want only good documentation or at
 least whole, but incomplete documentation.
 The ticket should remain open, no matter if this stub is commited or not.

 Regards, Julian

From: Jukka Ruohonen <jruohonen@iki.fi>
To: gnats-bugs@NetBSD.org
Cc: reinoud@NetBSD.org, Julian Fagir <gnrp@komkon2.de>
Subject: Re: kern/32430: genfs lacking documentation
Date: Sat, 11 Jun 2011 14:37:00 +0300

 On Sat, Jun 11, 2011 at 11:25:03AM +0000, Julian Fagir wrote:
 >  The ticket should remain open, no matter if this stub is commited or not.

 Sure. The conclusion from the previous discussion round was:

 	1. Write section 4 pages for each file system (or fs component);
 	   i.e. e.g. tmpfs(4), mfs(4), genfs(4), and so on.

 	2. When appropriate, append the section 4 pages with the layout and
 	   used structures; i.e. e.g. tmpfs(5), mfs(5), ffs(5), and so on.

 	3. Write section 9 pages for the actual KPI.

 	4. Once the above are done, consider a summary page.

 The case (1) is doable without too dense file system hacking background, and
 I happy to commit each well-written page. This can include, for instance,
 general description and notes, pros & cons, history, authors, pointers to
 further documentation, and so on. The case (3) obviously requires some
 background in actual file system programming.

 - Jukka.

>Unformatted:

Home	PR Database Search