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
