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?
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
