Margot Miller wrote: > Mark, > > In this below scenario 2b, does it mean that if a project team > is not willing to change the native docs, then they must supply > a man page? Yes. Otherwise this case will set the very bad precedent (in my mind) that projects are not required to publicly document their OpenSolaris ARC interface classifications.
I am not necessarily wedded to man pages but making them grep through ARC materials for this information is not acceptable as Jim Carlson states. -- mark > > > 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 > > Thanks > Margot > > > 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
