RE: [Doxygen-users] referencing methods in generated code

[Glenn M. <gle...@vo...>]

Hi Jesper,

I can certainly see your point that the name targets within a Doxygen
HTML page would be more useful if they had meaningful names instead of
incremented "a#" names.=20

<a name=3D"a12" doxytag=3D"KDConfigWidget::addGroup">
<a name=3D"KDConfigWidget::addGroup" =
doxytag=3D"KDConfigWidget::addGroup">

I would like to see this, too. It would make hyperlinking from external
systems into the Doxygen generated stuff more predictable.

=3D=3D=3D=3D tale of my workaround =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D

In my world, I run Doxygen on several code projects. I also export
material from FrameMaker books. I merge all of these mini-HTML systems
into a single comprehensive HTML system.

Ideally, when I write about some code item in FM, I'd like to be able to
hyperlink it directly to where that code item. I couldn't, because I
could not rely on the targets set by Doxygen; the target "a12" may
change the next time Doxygen is run and it discovers added/removed code
items. Another problem for me is that the included deliverables change,
which could make a hyperlink from FM invalid. On top of this, having
multiple Doxygen projects in one system made it more difficult to get
readers to their desired code item.

The solution that I came up with was to provide a comprehensive index.
(They are more likely to turn to this anyway if they run across an item
of interest in the text.)

I had a Perl tool I wrote that post-processes all generated HTML files
in a given directory. I was using it to swap out copyright information
at the bottom and buttons at the top of each HTML file to get that
consistent look-and-feel. I found the doxytag quite useful when I
extended this Perl tool to add support for creating the comprehensive
index.

For all of the HTML files in a directory, this tool creates a temporary
file with a running list of index tokens (text plus URL) taken directly
from these doxytag anchors (or index tokens exported from FM).=20

They are easy to spot with a split statement. (a) I already know the
path and HTML file. (b) The 'name=3D"a12"' is easy to parse out from the
rest of the URL. (c) The text of doxytag is the code item and later
becomes the text for one of the hyperlinks.

Another tool I created in Perl, indexer, parses these temporary files
into a big list. In addition, I have it do what I call "word-chunking"
whereby natural boundaries (white space, punctuation, capitalization
changes) are used to create additional second level index tokens. This
even bigger list then gets alphebetized. I then go through the list,
generate 26 HTML index pages (A-Z), put official HTML syntax around
entries, and handle the first and second level index items.

Hence, for the example above, I'll eventually get these entries:

add
  ...
  <a href=3D"bogus.html#a12>KDConfigWidget::addGroup</a>=20
  ...
...
config
  ...
  <a href=3D"bogus.html#a12>KDConfigWidget::addGroup</a>=20
  ...
...
group
  ...
  <a href=3D"bogus.html#a12>KDConfigWidget::addGroup</a>=20
  ...
...
<a href=3D"bogus.html#a12>KDConfigWidget::addGroup</a>=20
...
widget
  ...
  <a href=3D"bogus.html#a12>KDConfigWidget::addGroup</a>=20
  ...
...

If the exact same entry (but different URL) appears more than once, I
start appending little "document" icons after the text which are
hyperlinked appropriately.

The end result is an index that not only spans mini-HTML systems coming
from Doxygen and FM, but also is useful to programmers. If they don't
remember the class name or whether it is "addGroup" or "groupAdd" or
what project it is in, they can still get to the topic through the index
by knowing just "add" or "group".=20

True, it explodes the index; I have about about 16,000 entries for one
product. However, the static HTML index pages are online and fast; it
isn't like you're thumbing throught the hundreds of pages of a paper
book. The index pages display in the navigation frame (to the left),
load fast, scoll easy, control the content frame (to the right), and
have navigation at the top and bottom to take you to the different
letters of the alphabet, TOC, and FTS. The index entries are more
reliable and not as intrusive as the FTS (which I get from DevaSearch).

As an aside, at one point I figured out how to extend the javascript for
the tree structure to my TOC and Index. (tree.js) This is the one that
has the expanding/collapsing levels. However, it didn't work at all in
Netscape and wasn't very reliable in IE when the number of entries for
my TOC got large. Multiple "static" pages (which are autogenerated one
time) could give the impression of collapsing/expanding at, say, the top
level and were found to be faster.

Just throwing some ideas out there for you.

Glenn Maxey
Technical Writer
Voyant Technologies, Inc.
1765 West 121st Avenue
Westminster, CO 80234-2301
Tel. +1 303.223.5164
Fax. +1 303.223.5275
gle...@vo...


> -----Original Message-----
> From: Jesper K. Pedersen [mailto:bl...@kl...]
> Sent: Wednesday, November 28, 2001 3:12 AM
> To: dox...@li...
> Subject: Re: [Doxygen-users] referencing methods in generated code
>=20
>=20
> Chris Niekel <cn...@zo...> writes:
>=20
> | On Mon, Nov 12, 2001 at 09:27:35AM +0100, Jesper K. Pedersen wrote:
> | > I would like to reference methods in the generated HTML,=20
> but looking at the
> | > HTML, I see that the named tags are somthing like "a3",=20
> rather than
> | > something including the method names.=20
> | >=20
> | > Example:
> | > <a name=3D"a1" doxytag=3D"KDConfigWidget::addGroup"></a>
> | >=20
> | > My question thus is, is it possible to reference this=20
> location using
> | > KDConfigWidget::addGroup rather than "a1"?=20
> |=20
> | Doxygen does this quite automatically with the automatic tags.
> | In your documentation, refer to KDConfigWidget::addGroup, or to
> | #addGroup. The link to the class will appear in the output.
> Right, but I want to refer to doxygen generated documentation from
> outside. i.e. from an HTML page, which is not under the control of
> doxygen.=20