Date: Wed, 18 Apr 2001 03:03:57 -0700 From: Bengt Richter <bokr@accessone.com> To: freebsd-doc@freebsd.org Subject: Re: Programmers Documentation Project Message-ID: <5.0.2.1.1.20010418005646.00aef0d0@mail.accessone.com> In-Reply-To: <002101c0c7c4$dabada50$0200000a@satan> References: <001901c0c769$e2282870$0200000a@satan> <20010417144932C.jkh@osd.bsdi.com> <000701c0c78f$de88ec60$0200000a@satan>
next in thread | previous in thread | raw e-mail | index | archive | help
At 00:03 2001-04-18 -0500, you (Daryl Chance) wrote: >So does anyone see a use for this type of documentation? I would >like to know before I start work on this :). > >Jordan? > > > so basically, if you want to do it, heres your straight-jacket > > and path to your favorite editor eh? :) > > > > I really would like to do this, but I don't want to do it alone :). > > What I eventually want, is understanding enough of the code to be > > able to commit code back to the FBSD community and I figured that > > commenting code would be an easy way to get in there, tinker with > > code, without actually breaking anything. > > > > Btw, I did check the info you gave me Murray, and it's not what I > > was looking for :). What I'm lookin for is something like this: > > http://www.blur.com/blurbeta/Beta/source/maxclasslib/docs/html/index.html > > > > and AFAIK, it doesn't exists for FBSD. To any of the commiters > > to FreeBSD, does this seem useful? Or just wasted time? > > > > If it doesn't seem like wasted time to people, I start on it :). My feeling is that there are multiple separate issues involved: 1) Making pleasant-to-the-eye renderings of the information (e.g. doxygen) 1a) Making alternate "views" of the info available to zoom in/out, etc. 2) Making program data per se available. It seems to me that even with hints in the comments, a (quite-)pretty printer can only go so far. I would ultimately like to tap into the kind of information the compiler supplies as symbolic debug info, and in its warnings, and to reflect conditional choices exercised during a make. IOW, I see automated program documentation as a logical extension of symbolic debug options and listing options for compilers. It might be best to output an intermediate form of the info, rather than generate a particular documentation format directly. 3) Making semantic information available. That's where human commentary comes in. And some kind of standardized tagging syntax can make it possible to integrate it usefully with automated program data. If a big-time effort were to be started, this kind of enhancement to compilers is where I'd personally like to see it go. In combination with a standardized comment-tagging methodology, nicely commented set/use tables, data flow diagrams (think pdf a la circuit diagrams?), etc., could be possible, representing, e.g., the kernel you actually generated, instead of a mass of ill-separated possibilities. As always, refining the concept and checking history before jumping into coding is probably a good idea. There is at least partial precedent in cygnus' source navigator and something called global, as well as doxygen, and I'm sure others, but AFAIK nothing that would reflect conditionals in a make, and exclude (or at least grey out) what's not included (and also dead code?). Enumerating template instantiations and somehow showing hidden object temporaries created and destroyed as a side effect of expression evaluation or parameter passing/result returning could be nice too. Automatically marking pure (no side effects) functions as such might be nice too. And to include compiler-emitted truncation warnings and such via automatically generated comment patches could be useful, if concise. One possibility I see as helping humans document, would be an optional output that could be a series of HTML forms asking for missing information. E.g., if it were standard to specify units for variables in tagged comments, a form would be spit out asking about the item, with a slot for data entry, if no tagged comment were found for the item. Served by Apache with a little CGI scripting to process the inputs, the CGI might even be able to generate directly usable patches to insert comments into the code source. The HTML forms just have to carry enough context-linking info to return back to the CGI script/program. I could envision code documentation collaboration over the net using this kind of mechanism for standard semantic info such as for data, objects, methods, execution control conditions, etc. Of course, manuals and such are still pretty much human labor. Thank you for your time. Regards, Bengt Richter To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5.0.2.1.1.20010418005646.00aef0d0>