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
- if someone else built it, and there is IF stability info, we'll
support it via
the language-specific documentation facilities
- 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.
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.
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.
-tdc
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
>
