[Biojava-dev] javadoc taglets
Matthew Pocock
matthew_pocock@yahoo.co.uk
Thu, 28 Nov 2002 17:39:19 +0000 (GMT)
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