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

Naive question, wouldn't it be impractical/annoying to enforce that?

On Jun 3, 2009, at 08:43, David M. Lloyd wrote: > 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 _______________________________________________ jboss-development mailing list jboss-development(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jboss-development