On Fri, May 02, 2008 at 03:53:26PM -0700, Philip Brown wrote: > Errr.. are you implying here, that even "private" interfaces, are actually > documented in some degree, by these arc case logs you reference here?
Very often, they are. > ?? I'm not talking about Documentation, docs.sun.com style. I'm talking > along the level of 'code comments' level of documentation. You have the code, so you have the comments. If there are pieces of code that are crying out for comments but don't have them, please file bugs. I don't understand what you're asking for here. > You seemed to imply(in longer stuff I'm not quoting here) that documentation > is a big "cost sinkhole" that is usually a poor ROI, so sun would be foolish > to insist on documenting interfaces. Who cares? How Sun spends its money is a matter for that company's managers, directors, and shareholders; we are quite correctly not consulted. The *relevant* questions here are: 1. What are appropriate levels of commitment? 2. What are the documentation / ARC materials requirements for each? These are OpenSolaris rules that we collectively control, not Sun investment decisions for that company's leadership to make. Presently, the rules for (1) are described by the interface taxonomy that has been cited many times herein. You seem to have moved away from "Private must die" and on to "some minimal level of documentation should be required even for Private interfaces if they are part of something sufficiently complex to require ARC review". Right? Thankfully, this is already basically true. The ARC materials often include things like design documents that may not be strictly necessary for architecture review but provide helpful information for understanding the architecture and serve as a long-term repository of information for other engineers. Moreover, they have to describe what the interfaces are at least in sufficient detail that the ARC can be satisfied that they are correctly classified. These materials are, for new cases and a large and growing number of old ones, available to the general public (indeed, new cases are OpenSolaris cases, not Sun cases and have been for some time). Is it reasonable to boil down your position to "I'd sure like all the old Sun-era ARC case materials"? If so, you can help by identifying certain cases in the list of old, close cases that are likely to be of high value and requesting that they be opened via the existing process. Repeat until done. In the meantime, avail yourself of the code (much of which is very well commented) and the mailing lists to understand how things work. Quite honestly, access to the SWAN notwithstanding, the OpenSolaris engineering documentation situation is far better than for any other codebase of comparable size that I have ever observed. This does not mean we cannot do better or should not try, but it seems inconsistent with the bitter tone of your messages. > spending person-hours in assisting "the community" to efficiently take full > advantage of the code, rather than a "here's the code, now make it better > for us, for free" attitude. Can we invoke a variant of Godwin's Law when this argument is made? -- Keith M Wesolowski "Sir, we're surrounded!" Fishworks "Excellent; we can attack in any direction!"
