Tom Childers wrote: > Mark, > > This is really good. The bottom line seems to be: > > - if we build it, we will use our own interface stability > classifications, and > deliver them via language-specific documentation facilities Yes. > > - if someone else built it, and there is IF stability info, we'll > support it via > the language-specific documentation facilities Right. > > - if someone else built it, but IF stability info is inadequate, > we can add a man > page, and urge the team to add IF stability info to the > language-specific doc. Yes. > > Since man pages are the de facto language-specific IF doc for C/C++, > can we simplify the third option to state: > > - if someone else built it, but there is inadequate IF stability > info, we urge the team > to add IF stability info to the language-specific doc. That's what the "strongly urge" language meant to imply. > > In other words, add a TCA to the opinion. I don't think we add value > by requiring a man page in one specific situation. If man pages are > not consistently generally available for Java/Python/etc., I don't > think an occasional page will help anything. A TCA would certainly be in the spirit of "strongly urge"
-- mark > > On May 19, 2009, at 3:23 PM, Mark A. Carlson wrote: > >> During the case discussion today, I took the AI to help Michael >> Kearney draft >> a minority opinion. There may be other minority opinions, but if this >> looks >> close to something you would sign on to, I am open to small changes. >> >> -- mark >> >> >> 5. Minority Opinion >> >> Background >> >> It is not typical for programmers working with non C/C++/Assembler >> files, such as Java Jar files, to determine the >> Exported Interface stability level using the man command. Java >> programmers depend on Javadoc, Python programmers >> depend on pydoc and so forth to document interfaces and the >> stability would best be indicated there. >> Approval of OpenSolaris projects have been inconsistent in >> preferring man pages or native documentation. This opinion seeks >> to clarify the issue and define a policy for all such cases going >> forward. >> >> Best Practice >> >> Case A - Sun Developed Components >> >> 1) Sun project team developing a Jar file shall document the >> ARC interface classification in the native documentation. (i.e. >> Javadocs) >> >> Case B - Components imported from external OSS Communities >> >> 1) The OSS Community documents the interface classification in >> their native documentation >> >> a) OpenSolaris project team agrees with the classification >> and supports it >> - Javadoc or other native documentation required >> (unchanged) >> - No man page shall be allowed >> >> b) OpenSolaris project team disagrees with the >> classification >> - Javadoc or native documentation required, but >> project team must change the OSS documentation >> to match the project team's classification >> - No man page shall be allowed >> >> 2) OSS Community does not document interface classification in >> their native documentation >> a) OpenSolaris project team is strongly encouraged to >> update the native documentation to reflect the OpenSolaris project >> team >> classification. >> - Changed Javadoc or other native documentation required >> - No man page shall be allowed >> b) OpenSolaris project team cannot support deltas to the >> native documentation >> - Unchanged Javadoc or other native documentation >> required >> - A man page shall be provided >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc at opensolaris.org >> > -- <http://www.sun.com> * Mark A. Carlson * Sr. Architect *Systems Group* Phone x69559 / 303-223-6139 Email Mark.Carlson at Sun.COM
