Hi Anthony,
Thanks for your suggestions. However, my experience regarding the placement of
documentation files is the same as Tom’s: The directory paths are
non-predictable and pretty much change with every run. That might be related to
new source files being added, but adding new files is more or less an everyday
process. No matter what, permanent paths definitely don’t work for us (believe
me, I’ve tried).
The idea of the wiki interpreting the tag files sounds interesting, I’ll try
digging into this. However, in our case, the Wiki and the doxygen documentation
are on two different machines which don’t really know much about each other, so
I’m not sure if it even will be possible to make the tagfiles visible.
Since you were asking, the Javadoc tool handles this actually in a
straightforward way: The generated documentation represents the source files’
package structure. Thus, the directory paths are not only stable, but actually
predictable just by looking at the source code. Most likely this mechanism
relies on Java’s specific requirement that the directory structures must match
the package structures. As doxygen has a multi-language approach, I suppose
something similar won’t be easy to implement (if possible at all). But I don’t
know enough about doxygen’s internals to really asses this question…
Mit freundlichen Grüßen
Raimund Klein
EDV / Software Entwickler
BERENBERG BANK
Joh. Berenberg, Gossler & Co. KG
Neuer Jungfernstieg 20
20354 Hamburg
Telefon +49 40 350 60-8129
Telefax +49 40 350 60-955
E-Mail raimund.kl...@berenberg.de
www.berenberg.de <outbind://75/www.berenberg.de>
Sitz: Hamburg - Amtsgericht Hamburg HRA 42659
Von: Anthony Foiani [mailto:anthony.foi...@gmail.com]
Gesendet: Mittwoch, 27. Februar 2013 13:22
An: Tom Tanner; Klein, Raimund
Cc: doxygen-users@lists.sourceforge.net
Betreff: Re: [Doxygen-users] CREATE_SUBDIRS
Tom, Raimund --
2013/2/27 Klein, Raimund <raimund.kl...@berenberg.de>
My question regarding this: What is a „huge“ amount of source files? Are there
any known values for this? We’re generating the doxygen docs every night, but
because of the unpredictable placement of files in the subdirectories, we can
never have permanent links to any file inside there e.g. from our Wiki or Jira.
However, I tend to think our projects are indeed non trivial regarding the
number of source files, so I’d appreciate if anyone had somewhat substantial
data on this.
On Wed, Feb 27, 2013 at 4:42 AM, Tom Tanner (BLOOMBERG/ LONDON)
<ttann...@bloomberg.net> wrote:
I'm not sure precisely what huge is but I have had a situation where we
actually hit a limit on the number of files in a directory.
And it's almost impossible to clean up a directory that large.
So I'd like to go to subdirs. But I can't because there appears to be no
predictability about where files will go (or at least I haven't had an answer
on this group to my last question on the subject) and it is then impossible to
link to individual pages from a wiki because you don't know where they'll be
next time you generate the doxygen pages.
If you request that doxygen create a tag file, it will include the path and
anchor for your entites, e.g.,
<member kind="function">
<type>void</type>
<name>pushStringVector</name>
<anchorfile>d3/dd7/UNAPReader_8c.html</anchorfile>
<anchor>abbd334d33e2b450ebe9d3810a0c8adc8</anchor>
<arglist>(StringVector *v, const char *val)</arglist>
</member>
So it's possible (but potentially ugly) to use that tag file to update your
wiki after every documentation rebuild.
From a quick look at the code, those values (anchorfile and anchor) should be
stable. Once an entity has been documented, it should remain the same unless
the file is renamed (or if the doxygen config file is modified...) Signature
changes will modify the anchor, but will not change the anchorfile.
That will only work with long filenames, btw. Short filenames are just numbers
since discovery, and not cached between runs -- so if a new file shows up in
the code base, all later files will get different filepaths.
The actual algorithm for filename seems to use the last 12 bits of an MD5 over
the escaped filename (see "convertNameToFile" in src/util.cpp); there are even
comments pointing out that at least one earlier method was not stable.
That means that you might be able to have a hook in your wiki to take some
custom markup, look up the location in the tag file, and update the wiki
document upon update.
Alternately, you can massage the tag file into an HTML file, then have your
wiki pages point into that index. That way, you only have to recreate the
index as a part of your docs rebuild -- but you might have to require an extra
click or some javascript to get to the final documentation.
Finally, the best option might be to extend your wiki engine to understand
these tags, so you can just link to the function name, and have the wiki engine
look up the correct current link automatically...
How does JavaDoc handle this?
Hope this helps.
Best regards,
Anthony Foiani
Diese Nachricht einschliesslich etwa beigefuegter Anhaenge ist vertraulich und
kann dem Bank- und Datengeheimnis unterliegen oder sonst rechtlich geschuetzte
Daten und Informationen enthalten. Wenn Sie nicht der richtige Adressat sind
oder diese Nachricht irrtuemlich erhalten haben, informieren Sie bitte sofort
den Absender über die Antwortfunktion. Anschliessend moechten Sie bitte diese
Nachricht einschliesslich etwa beigefuegter Anhaenge unverzueglich vollstaendig
loeschen. Das unerlaubte Kopieren oder Speichern dieser Nachricht und/oder der
ihr etwa beigefuegten Anhaenge sowie die unbefugte Weitergabe der darin
enthaltenen Daten und Informationen sind nicht gestattet. Wir weisen darauf
hin, dass rechtsverbindliche Erklaerungen namens unseres Hauses grundsaetzlich
der Unterschriften zweier ausreichend bevollmaechtigter Vertreter unseres
Hauses beduerfen. Wir verschicken daher keine rechtsverbindlichen Erklaerungen
per E-Mail an Dritte. Demgemaess nehmen wir per E-Mail auch keine
rechtsverbindlichen Erklaerungen oder Auftraege von Dritten entgegen.
Sollten Sie Schwierigkeiten beim Oeffnen dieser E-Mail haben, wenden Sie sich
bitte an den Absender oder an i...@berenberg.de. Please refer to
http://www.berenberg.de/my_berenberg/disclaimer_e.html for our confidentiality
notice.
------------------------------------------------------------------------------
Everyone hates slow websites. So do we.
Make your web apps faster with AppDynamics
Download AppDynamics Lite for free today:
http://p.sf.net/sfu/appdyn_d2d_feb
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
