[Doxygen-users] Some comments about templates.

[Ian B. <ian...@pr...>]

Hello All,
	I've been using Together C++ for some time now to generate
documentation from our sources.  Recently, however, I have moved to Doxygen
because it is cheaper and does a better job in most cases. The  only
challenge it has at the moment is dealing with templates. I have noticed
some discussion lately  about this subject and I thought it may be
interesting to let you know how Together goes about solving  this problem.

Templates, at least in my experience, are mainly used for collection classes
... lists, arrays, hash  tables etc. In this respect, showing the
associations in the collaboration diagram are more important to
understanding the code than showing the inheritance hierarchy. The problem
is that to write a parser that can draw a sensible collaboration diagram
from an optimised collection class template is a huge amount of  work.
Together allows the user to specify 'blueprints' ... these are basically
string matching expressions  which give the parser hints as to how to draw
the collaboration graphs. I haven't looked into the code of  Doxygen, so I
don't know if this type of thing would be possible to integrate. It may,
however, provide a  quicker method of documenting template hierarchies and
collaborations than straight code parsing. In the  case of the collaboration
diagrams it would also provide a method of describing what the collection
holds without the extraneous template implementation details also being
shown.

I have attached a section of my Together configuration file wich gives
Together the information necessary to document the MFC Collection Classes.
It's fairly self explanatory and should help give you some idea about what
I'm talking about.

For more information, download the trial version of Together and have a play
... Doxygen does most things  better, but it's still an interesting
comparison. (http://www.togethersoft.com)

Ian Brown

----------------------------------------------------------------------------
--------

#
# Parser's blueprints are defined with only one pattern string and without
quotes.
# In addition to codegen blueprints, you can use %Any% in patterns.
#  %Any% - any token.
# Each attribute declaration or design comment is compared against the
blueprint pattern
#  and if recognized, forms a link of the corresponding type.
# NOTE: the first matched blueprint is used.
# Additional properties (tags) can be defined as sub-property for particular
blueprint.
# NOTE: tag values directly specified in design comments override the ones
from blueprint.
#
# Add some defines for MFC containers...

parser.cpp.blueprint.link.Association from Typed pointer list =
CTypedPtrList<CPtrList, %dst%*> %Name%
parser.cpp.blueprint.link.Association from Typed pointer
list.supplierCardinality = "0..*"

parser.cpp.blueprint.link.Association from Typed pointer array =
CTypedPtrArray<CPtrArray, %dst%*> %Name%
parser.cpp.blueprint.link.Association from Typed pointer
array.supplierCardinality = "0..*"

parser.cpp.blueprint.link.Aggregation from CArray = CArray<%dst%, %dst%&>
%Name%
parser.cpp.blueprint.link.Aggregation from CArray.link = "aggregation"
parser.cpp.blueprint.link.Aggregation from CArray.supplierCardinality =
"0..*"

parser.cpp.blueprint.link.Aggregation from CList = CList<%dst%, %dst%&>
%Name%
parser.cpp.blueprint.link.Aggregation from CList.link = "aggregation"
parser.cpp.blueprint.link.Aggregation from CList.supplierCardinality =
"0..*"

# NOTE: uncomment the following lines to treat pointer to class as
aggregation (not recommended).
;parser.cpp.blueprint.link.Aggregation from pointer = %dst% * %Name%
;parser.cpp.blueprint.link.Aggregation from pointer.link = "aggregation"
;parser.cpp.blueprint.link.Aggregation from pointer.supplierCardinality =
"1"

parser.cpp.blueprint.link.Association from pointer = %dst% * %Name%
parser.cpp.blueprint.link.Association from pointer.supplierCardinality =
"0..1"

parser.cpp.blueprint.link.Association from pointer_ = %Any% %dst% * %Name%
parser.cpp.blueprint.link.Association from pointer_.supplierCardinality =
"0..1"

parser.cpp.blueprint.link.Association from reference = %dst%& %Name%
parser.cpp.blueprint.link.Association from reference.supplierCardinality =
"1"

# NOTE: uncomment the following lines to treat template container of
pointers to class as aggregation  (not recommended).
;parser.cpp.blueprint.link.Aggregation from template of pointers =
%Any%<%dst%*> %Name%
;parser.cpp.blueprint.link.Aggregation from template of pointers.link =
"aggregation"
;parser.cpp.blueprint.link.Aggregation from template of
pointers.supplierCardinality = "1..*"

parser.cpp.blueprint.link.Association from template of pointers =
%Any%<%dst%*> %Name%
parser.cpp.blueprint.link.Association from template of
pointers.supplierCardinality = "0..*"

# NOTE: to threat aggreration as composition comment line with "aggregation"
and uncomment one with  "aggregationByValue"
parser.cpp.blueprint.link.Aggregation = %dst% %Name%
parser.cpp.blueprint.link.Aggregation.link = aggregation
;parser.cpp.blueprint.link.Aggregation.link = "aggregationByValue"

# NOTE: to threat aggreration as composition comment line with "aggregation"
and uncomment one with  "aggregationByValue"
parser.cpp.blueprint.link.Aggregation from template = %Any%<%dst%> %Name%
parser.cpp.blueprint.link.Aggregation from template.link = "aggregation"
;parser.cpp.blueprint.link.Aggregation from template.link =
"aggregationByValue"
parser.cpp.blueprint.link.Aggregation from template.supplierCardinality =
"1..*"