4

I have written a library, that uses another 3rd party library. This 3rd party library is provided online at a particular website. I have successfully used DoxyGen to document MY project, but I’m having great difficulty getting it to generate links to the 3rd party, online, documentation.

I figured out that I can create “dummy” entries for those classes in my files, and have pages generated for them, these pages have a link to the online documentation. The disadvantage to this is, I am forced to have a page on MY docs that are nothing but a link. Ideally, clicking on a 3rd party class should take the user DIRECTLY to the online documentation, rather than making users to go though a “do-nothing-but-link” page.

I have attempted to use External tag files for this, but keep getting errors when doxygen runs, and the classes tagged remain not-links in the output. I have not found ANY examples that use a manually created tag files to reference online documentation, but based on the wording of the doxygen instructions, it appears this should be doable. My current tag file currently looks like this(though I have tried quite a few variations): ExternalTags.xml

<?xml version="1.0" encoding="UTF-8" standalone="true"?>
<tagfile>
<compound kind="class">
<name>Vector3</name>
<filename>Vector3.html</filename>
</compound>
</tagfile>

And my config file contains the following line(also tried many variations):

TAGFILES               = "externalTags.xml = http://docs.unity3d.com/ScriptReference/"

When the tag file is REMOVED from the configuration, doxygen runs without any errors. WITH the tag file option included, doxygen always generates the following error:

lookup cache used 941/65536 hits=6682 misses=1048
finished...
error: Fatal error at line 1 column 1: error while parsing element
error: Fatal error at line 1 column 1: error while parsing prolog

How can I resolve these errors, and get the links to be generated properly in the doxygen output?

Glurth
  • 290
  • 1
  • 17
  • 1
    Found any solution for this? – magol Aug 15 '16 at 21:05
  • 1
    I've put it on the shelf for a while, never figured it out though. – Glurth Aug 16 '16 at 22:12
  • 2
    @Glurth I'm not sure about the spaces in the TAGFILES configuration item. With which version of doxygen did you try last (current version is 1.8.15) Also the information is a bit limited. The error suggests an incorrect tag file, but I'm not sure could you create a small project signalling the problem (note with doxygen 1.8.15 you get the differences between the standard Doxyfile and the used Doxyfile by means of `doxygen -x ` – albert Jan 15 '19 at 09:18

2 Answers2

4

Finally figured it out: it appears, I was missing part of the tag-file contents (namespace section).
When using the following tag-file contents, I got no error, and the links to Unity Types specified in the tag-file appeared properly in the output.

Also, note the filename fields do NOT include the .html extension.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<tagfile>
  <compound kind="namespace">
    <name>UnityEngine</name>
    <filename></filename>
    <class kind="class">UnityEngine::PlayerPrefs</class>
    <class kind="class">UnityEngine::Vector3</class>
  </compound>
  <compound kind="class">
    <name>UnityEngine::PlayerPrefs</name>
    <filename>PlayerPrefs</filename>
  </compound>
  <compound kind="class">
    <name>UnityEngine::Vector3</name>
    <filename>Vector3</filename>
  </compound>
</tagfile>

Probably not related to the issue, but have not tested changing it back, I renamed the tagfile: unity3d-doxygen-web.tag.xml

Glurth
  • 290
  • 1
  • 17
  • I need the `.html` extension. How do I prevent Doxygen from trimming it? Adding it to the end of the line doesn't work. – AntumDeluge Jan 26 '22 at 01:34
  • There appears to be a [bug in Doxygen v1.9.3](https://github.com/doxygen/doxygen/issues/9075) that trims the .html extension. I ended up creating a Python script to parse the generated HTML files & fix the URLs. – AntumDeluge Jan 26 '22 at 09:14
1

It's been a year, but if someone else hits this, the issue comes from the first line:

<?xml version="1.0" encoding="UTF-8" standalone="true"?>

should read as:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

Doxygen just does not recognize true as a valid keyword.

spectras
  • 13,105
  • 2
  • 31
  • 53