avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stephen McConnell <mcconn...@apache.org>
Subject Re: Minimal set of component attributes?
Date Wed, 19 Mar 2003 02:20:33 GMT


dvillevalois@phpapp.org wrote:

>>not unless we want to violate the javadoc spec. It identifies "." as the
>>name space separator.
>>
>>And there is no reason why "." could not be used for that very purpose
>>aswell.
>>    
>>
>
>I think the . namespace separator is meant to follow java namespaces. Said in
>another manner, this means, for your purpose, that you must say:
>
>@org.apache.avalon.service
>
>and not
>
>@avalon.service
>
>Does this seem correct to you ?? 
>

Hi Didier:

The javadoc spec *states* that the javadoc phrase is an '@' character 
following by a string representing a key followed by a value terminated 
by a line break. The references in the spec concerning namespacing are 
suggestions only with the reference to the fact that Sun does not and 
will not include a period keys it defines. In practice there is no 
namespace notion (i.e. no formal way to partition tag relative to a 
particular domain) which means you have to devise your own. Given the 
function of a javadoc comment - basically a tagged single line of text, 
you really want to keep the key as short as possible for reasons of 
legibility (simply because you can't throw a line break in there) which 
means the @org.apache.avalon.service becomes overly verbose once you 
start using values as well. So it's a compromise.

The namespace separation issue can be whatever you like but there are 
problems you can encounter. A '.' character is what the javadoc tool 
will check for when processing non-standard tags and is "required" if 
you want to avoid javadoc warning warnings (unless you use Taglets which 
bypass the issue). The ':' character means more to me but at the end of 
the day it's nothing to get excited about.

What I find more interesting is using stuff like qdox for meta data 
generation in combination with Taglets so we get coverage in terms of 
automated meta info generation combined with the potential to leverage 
the same information in better component documentation under the 
generated javadoc.

Cheers, Steve.

-- 

Stephen J. McConnell
mailto:mcconnell@apache.org
http://www.osm.net




---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org


Mime
View raw message