Re: [jboss-dev] building the documentation for JBoss public and private API...

But of course in AS 6, private APIs won't be accessible to customer deployments anyway, since we'll have nice API/impl separation and we'll be fully modularized. Right guys? RIGHT?!? - DML On 06/02/2009 09:36 PM, Scott Marlow wrote: > One illegal usage might be detecting that a private (JBoss > internal) API was used by a customer application. This would be > useful for our customers to know as private API can change > unexpectedly from release to release. > Applications that use private APIs will need more refactoring > during migration to a new AS release. > Perhaps we could also have a usage check for unsupported APIs (some > projects have contributions that may be considered experimental). > David M. Lloyd wrote: >> Illegal usages such as what? >> >> - DML >> >> On 06/01/2009 04:04 PM, Emmanuel Bernard wrote: >>> +1 for annotations as we could also flag illegal usages at >>> compile time via an annotations compiler. >>> >>> On Jun 1, 2009, at 17:00, David M. Lloyd wrote: >>> >>>> On 06/01/2009 03:19 PM, Scott Marlow wrote: >>>>> We were just talking about building a list of all JBoss AS >>>>> public API calls. This will be used to document the public API >>>>> versus what is considered private (we will include only the >>>>> public API in this "public api" documentation). >>>>> One idea mentioned already is that we could use an annotation >>>>> (e.g. something like @publicAPI mentioned elsewhere http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...) >>>>> . We would then build the "public API" documentation based on >>>>> the @publicAPI annotations (the how to be determined). >>>>> We might want to also include a @privateAPI tag, for source >>>>> files that contain a mix of public and private API (or maybe we >>>>> should move anything private into separate modules). >>>> >>>> The way I traditionally tackle this is by using package-private >>>> access for non-API stuff in the API package. Otherwise, a >>>> taglet would be a great way to do this (annotations are probably >>>> overkill). Javadoc may be an old technology but it's still >>>> decent. >>>> >>>> One thing I also have for Remoting 3 is a set of javadoc tags >>>> that I can stick on a class or interface which causes a generic >>>> explanation to be appended to the javadoc (like "This interface >>>> is intended to be implemented by the end user" or "This >>>> interface is intended for service providers, so new methods may >>>> be added without notice", etc). I can provide a link as soon as >>>> I get around to getting the javadoc published for 3.1. >>>> >>>> - DML >>>> _______________________________________________ >>>> jboss-development mailing list >>>> jboss-development(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/jboss-development >>> >>> _______________________________________________ >>> jboss-development mailing list >>> jboss-development(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/jboss-development >> _______________________________________________ >> jboss-development mailing list >> jboss-development(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/jboss-development > _______________________________________________ > jboss-development mailing list > jboss-development(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/jboss-development _______________________________________________ jboss-development mailing list jboss-development(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jboss-development