[Biojava-dev] javadoc taglets
Schreiber, Mark
mark.schreiber@agresearch.co.nz
Fri, 29 Nov 2002 09:02:58 +1300
That looks pretty good!
In javadoc it is possible to produce only javadocs for public methods or
public/package depending on the level of documentation you want.
Would it be possible or even a good idea to produce user only javadocs
so all the methods they don't really need to use are hidden?
- Mark
> -----Original Message-----
> From: Matthew Pocock [mailto:matthew_pocock@yahoo.co.uk]
> Sent: Friday, 29 November 2002 6:39 a.m.
> To: Matthew Pocock; biojava-dev@biojava.org
> Subject: Re: [Biojava-dev] javadoc taglets
>
>
> Just to follow up on my last post...
>
> In my personal cvs copy I have got a taglet working to
> deal with these applicability tags. I've gone through
> AnnotationType and added these tags. It realy makes the
> process of documenting much easier, as it is clear who your
> intended audience is for each headline you write. Also, as
> someone reading the docs, you can quickly see if a method is
> meant to be used by you or in your circumstances. This
> coupled with brief usage code at the top of the main files
> should go a long way to making things less intimidating.
>
> Below (as text, not HTML) is what happens when I
> javadoc AnnotationType. I would send it as an
> attachment, but attachments seem to be being rejected
> by our list server at the moment. Notice that the
> class and methods and fields may have "Intended for:"
> comments. We can customize this output in many ways if
> we like it dumped in-place (as it is now) e.g. we
> could put it in nicely colored tables or provide links
> back to deffinitions of Power Users, Developers and
> Users. To get this info to appear in the package and
> method tables would require us to write an extention
> to the standard doclet (which I can't be bothered to
> do).
>
> Please give me some feedback about this. I think it
> makes things more readable, but it will be some effort
> to push through. We can add as many other classes of
> user as we see fit. Perhaps powerUser should become
> developer, and the current developer tag should move
> to Implementor.
>
> Matthew
>
> Overview Package Class Use Tree
> Deprecated Index Help
> PREV CLASS NEXT CLASS FRAMES NO FRAMES All
> Classes
> SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL:
> FIELD | CONSTR | METHOD
> org.biojava.bio
> Interface AnnotationType
>
> All Known Implementing Classes:
> AnnotationType.Abstract
>
> public interface AnnotationType
>
> A type to constrain annotation bundles.
>
> AnnotationType instances can be used to validate an
> Annotation to check that it has the appropriate
> properties and that they are of the right type.
>
> AnnotationType is a powerful constraint-based language
> for describing sets of Annotation bundles. It works by
> assuming that any given Annotation may have any set of
> properties defined. If it matches a particular AnnotationType
> instance, then each defined property must be of a value that
> is acceptable to the type, and each undefined property must
> be allowed to be absend in the type.
>
> The constraint on any given property is two-fold.
> Firstly, there is the PropertyConstraint associated
> with it. This is an interface that will accept or
> reject any given Java object. Effectively, this can be
> thought of as a set membership operator over all
> objects. Seccondly, CardinalityConstrait defines a
> legal number of values that the property can hold. For
> example, if you had a car Annotation, you may wish to
> associate it with exactly 4 values under the Wheel
> property. CardinalityConstraint is a simple wrapper
> arround org.biojava.bio.symbol.Location, and it is
> Location that is used to represent the legal range of
> cardinalities. CardinalityConstraint provides some usefull
> standard Location instances such as ZERO, ONE and ANY.
>
> It is usually left up to the AnnotationType instance
> to work out how multiple values should be packed into
> a single property slot in an Annotation instance.
> Commonly, things that are allowed a cardinality of 1
> will store one value directly in the slot. Things that
> allow multiple values (and optionaly things with one
> value) will usualy store them within a Collection in
> the slot. This complexity is hidden from you if you
> use the accessor methods built into AnnotationType,
> setProperty() and getProperty().
>
> Since:
> 1.3
> Author:
> Matthew Pocock, Keith James (docs)
> Intended for: Developers
> Implementing your own AnnotationType
> implementations to reflect frame, schema or ontology
> definitions Intended for: Power users
> Make AnnotationType instances that describe what
> should and should not appear in an Annotation bundle
> Constrain FeatureFilter schemas by Annotation
> associated with the features
> Provide meta-data to the tag-value parser for
> automatically generating object representations of
> flat-files
> Intended for: Users
> Using AnnotationType instances that you have been
> provided with e.g. from
> UnigeneTools.LIBRARY_ANNOTATION
>
> Nested Class Summary
> static class AnnotationType.Abstract
> An abstract base class useful for retrieving
> AnnotationType instances. static class AnnotationType.Impl
> An implementation of AnnotationType.
>
> Field Summary
> static AnnotationType ANY
> The type that accepts all annotations and is
> the supertype of all other annotations.
> static AnnotationType NONE
> The type that accepts no annotations at all
> and is the subtype of all other annotations.
>
> Method Summary
> Location getCardinalityConstraint(java.lang.Object
> key)
> Retrieve the cardinality constraint
> associated with properties.
> Location getDefaultCardinalityConstraint()
> Get the CardinalityConstraint that will be
> applied to all properties without an explicit binding.
> PropertyConstraint getDefaultPropertyConstraint()
> Get the PropertyConstraint that will be
> applied to all properties without an explicit binding.
> java.util.Set getProperties()
> Retrieve the complete set of properties that
> must be present for an Annotation to be accepted by
> this AnnotationType.
> java.util.Collection getProperty(Annotation ann,
> java.lang.Object property)
> Get the Collection of values associated with
> an Annotation bundle according to the type we believe
> it to be.
> PropertyConstraint
> getPropertyConstraint(java.lang.Object key)
> Retrieve the constraint that will be applied
> to all properties with a given key.
> boolean instanceOf(Annotation ann)
> Validate an Annotation against this
> AnnotationType.
> void removeProperty(Annotation ann, java.lang.Object
> property, java.lang.Object value)
> Remove a property key, value pair from an
> Annotaiton instance.
> void setConstraints(java.lang.Object key,
> PropertyConstraint con, Location card)
> Set the constraints associated with a
> property.
> void setDefaultConstraints(PropertyConstraint pc,
> Location cc)
> Set the constraints that will apply to all
> properties without an explicitly defined set of
> constraints.
> void setProperty(Annotation ann, java.lang.Object
> property, java.lang.Object value)
> Set the property in an annotation bundle
> according to the type we believe it should be.
> boolean subTypeOf(AnnotationType subType)
> See if an AnnotationType is a specialisation
> of this type.
>
>
> Field Detail
> ANY
>
> public static final AnnotationType ANY
>
> The type that accepts all annotations and is the
> supertype of all other annotations. Only an empty
> annotation is an exact instance of this type.
>
> Intended for: Users
> Use this whenever an AnnotationType is needed by
> an API and you don't want to constrain anything
>
> NONE
>
> public static final AnnotationType NONE
>
> The type that accepts no annotations at all and is
> the subtype of all other annotations.
>
> Intended for: Users
> Use this whenever an AnnotationType is needed by
> an API and you want to make sure that all Annotation
> objects get rejected
>
> Method Detail
> instanceOf
>
> public boolean instanceOf(Annotation ann)
>
> Validate an Annotation against this
> AnnotationType.
>
> Parameters:
> ann - the Annotation to validate.
> Returns:
> true if ann conforms to this type and false if it
> doesn't.
> Intended for: Users
> Any time you wish to see if an Annotation bundle
> conforms to a type
>
> subTypeOf
>
> public boolean subTypeOf(AnnotationType subType)
>
> See if an AnnotationType is a specialisation of
> this type.
>
> An AnnotationType is a sub-type if it restricts
> each of the properties of the super-type to a type
> that can be cast to the type in the super-type. Note
> that this is not always a cast in the pure Java sense;
> it may include checks on the number and type of
> members in collections or other criteria.
>
> Parameters:
> subType - an AnnotationType to check.
> Returns:
> true if subType is a sub-type of this type.
> Intended for: Power users
> If you wish to check that one type is a more
> constrained version of another
>
> getPropertyConstraint
>
> public PropertyConstraint getPropertyConstraint(java.lang.Object key)
>
> Retrieve the constraint that will be applied to
> all properties with a given key.
>
> For an Annotation to be accepted, each key in
> getProperties() must be present in the annotation and
> each of the values associated with those properties
> must match the constraint.
>
> Parameters:
> key - the property to be validated.
> Returns:
> PropertyConstraint the constraint by which the
> values must be accepted.
> Intended for: Power users
> If you want to find out exactly what constraints
> will be applied to a particular propery key
>
> getCardinalityConstraint
>
> public Location
> getCardinalityConstraint(java.lang.Object key)
>
> Retrieve the cardinality constraint associated
> with properties.
>
> For an annotation to be acceptable, the property
> must have a number of values that matches the
> cardinality constraint. Common values are represented
> by static fields of Location.
>
> Parameters:
> key - the property to be validated
> Returns:
> a Location giving the number of values assocated
> with the property
> Intended for: Power users
> If you want to find out exactly what constraints
> will be applied to a particular propery key
>
> setConstraints
>
> public void setConstraints(java.lang.Object key,
> PropertyConstraint con,
> Location card)
>
> Set the constraints associated with a property.
>
> Parameters:
> key - the name of the property to constrain
> con - the PropertyConstraint to enforce
> card - the CardinalityCnstraint to enforce
> Intended for: Power users
> When you are building your own AnnotationType
>
> setDefaultConstraints
>
> public void setDefaultConstraints(PropertyConstraint
> pc,
> Location cc)
>
> Set the constraints that will apply to all
> properties without an explicitly defined set of
> constraints.
>
> Parameters:
> pc - the default PropertyConstraint
> cc - the default CardinalityConstraint
> Intended for: Power users
> When you are building your own AnnotationType
>
> getDefaultPropertyConstraint
>
> public PropertyConstraint
> getDefaultPropertyConstraint()
>
> Get the PropertyConstraint that will be applied to
> all properties without an explicit binding. This
> defaults to PropertyConnstraint.ALL.
>
> Returns:
> the default PropertyConstraint
> Intended for: Power users
> If you want to find out exactly what constraint
> will be applied to properties with no explicitly
> defined constraints
>
> getDefaultCardinalityConstraint
>
> public Location getDefaultCardinalityConstraint()
>
> Get the CardinalityConstraint that will be applied
> to all properties without an explicit binding. This
> defaults to CardinalityConstraint.ALL.
>
> Returns:
> the default CardinalityConstraint
> Intended for: Power users
> If you want to find out exactly what constraint
> will be applied to properties with no explicitly
> defined constraints
>
> getProperties
>
> public java.util.Set getProperties()
>
> Retrieve the complete set of properties that must
> be present for an Annotation to be accepted by this AnnotationType.
>
> Returns:
> the Set of properties to validate.
> Intended for: Power users
> Discover which properties have explicit
> constraints
>
> setProperty
>
> public void setProperty(Annotation ann,
> java.lang.Object property,
> java.lang.Object value)
> throws ChangeVetoException
>
> Set the property in an annotation bundle according
> to the type we believe it should be. This will take
> care of any neccisary packing or unpacking to
> Collections.
>
> Parameters:
> ann - the Annotation to modify
> property - the property key Object
> value - the property value Object
> Throws:
> ChangeVetoException - if the value could not be
> accepted by this annotation type for that property
> key, or if the Annotation could not be modified
> Intended for: Users
> Edit an Annotation bundle in a way compattible
> with this AnnotationType
>
> getProperty
>
> public java.util.Collection getProperty(Annotation
> ann,
>
> java.lang.Object property)
> throws
> ChangeVetoException
>
> Get the Collection of values associated with an
> Annotation bundle according to the type we believe it
> to be. This will take care of any neccisary packing or
> unpacking to Collections. Properties with no values will
> return empty Collections.
>
> Parameters:
> ann - the Annotatoin to modify
> property - the property key Object
> Throws:
> ChangeVetoException - if the value could not be
> removed
> Intended for: Users
> Edit an Annotation bundle in a way compattible
> with this AnnotationType
>
> removeProperty
>
> public void removeProperty(Annotation ann,
> java.lang.Object property,
> java.lang.Object value)
> throws ChangeVetoException
>
> Remove a property key, value pair from an
> Annotaiton instance. This will take care of any
> neccisary packing or unpacking to Collections.
>
> Parameters:
> ann - the Annotation to modify
> property - the property key Object
> value - the property value Object
> Throws:
> ChangeVetoException - if the Annotation could not
> be modified
> Intended for: Users
> Edit an Annotation bundle in a way compattible
> with this AnnotationType
>
> Overview Package Class Use Tree Deprecated
> Index Help
> PREV CLASS NEXT CLASS FRAMES NO FRAMES All
> Classes
> SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL:
> FIELD | CONSTR | METHOD
>
>
> --- Matthew Pocock <matthew_pocock@yahoo.co.uk>
> wrote: > Hi,
> >
> > In the 1.4 javadoc, they added the taglet API that
> > lets you drop in handlers for custom @tag
> > deffinitions. I've just written my first. It handles
> > @user, @developer, @powerUser tags. It will let us
> > tag
> > classes/methods with some indication of the intended
> audience. We can
> > work something out in the ant script
> > so that those of us unfortunate enough to be <1.4
> > can
> > still build docs.
> >
> > Does this sound like it's worth persuing, or am I
> > barking up the wrong tree?
> >
> > Matthew
> >
> > __________________________________________________
> > Do You Yahoo!?
> > Everything you'll ever need on one web page
> > from News and Sport to Email and Music Charts http://uk.my.yahoo.com
> > _______________________________________________
> > biojava-dev mailing list
> > biojava-dev@biojava.org
> > http://biojava.org/mailman/listinfo/biojava-dev
>
> __________________________________________________
> Do You Yahoo!?
> Everything you'll ever need on one web page
> from News and Sport to Email and Music Charts
> http://uk.my.yahoo.com >
_______________________________________________
> biojava-dev mailing list
> biojava-dev@biojava.org
> http://biojava.org/mailman/listinfo/biojava-dev
>
=======================================================================
Attention: The information contained in this message and/or attachments
from AgResearch Limited is intended only for the persons or entities
to which it is addressed and may contain confidential and/or privileged
material. Any review, retransmission, dissemination or other use of, or
taking of any action in reliance upon, this information by persons or
entities other than the intended recipients is prohibited by AgResearch
Limited. If you have received this message in error, please notify the
sender immediately.
=======================================================================