New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Entity references in XML command attributes are incorrectly handled (Origin: bugzilla #738167) #5652

doxygen opened this Issue Jul 2, 2018 · 0 comments


None yet
1 participant

doxygen commented Jul 2, 2018

status REOPENED severity normal in component general for ---
Reported in version 1.8.8 on platform Other
Assigned to: Dimitri van Heesch

On 2014-10-08 17:35:05 +0000, Carl Reinke wrote:

Given the following documentation comment (which is valid according to whatever tool Visual Studio invokes to produce a documentation XML file from C# code),

    /// <summary>
    /// Translates an <see cref="IDictionary&lt;K, V&gt;"/> to a ...
    /// <summary>

doxygen produces HMTL documentation such that the HMTL document contains

    <p>Translates an IDictionary&amp;lt;K, V&amp;gt; to a ...</p>

which renders as

    Translates an IDictionary&lt;K, V&gt; to a ...

On 2014-10-08 19:24:57 +0000, Carl Reinke wrote:

Sorry about the typos -- that should be a closing summary tag at the end of the documentation comment and "HTML" rather than "HMTL".

On 2014-12-18 15:55:24 +0000, Ben Spiller wrote:

+1 for this - it's a really serious bug and is making it very difficult for us
to use doxygen. The whole point of the C# XML input format is that it's valid
XML, and Visual Studio will complain or even fail to compile in some cases if
it isn't, so it's important that doxygen can cope with &lt; &gt; entity
references to specify the < and > characters in code snippets like this. 

It should be pretty simple to implement a find-replace preprocessor step for
key XML entities such as < and > (and it could be a configurable option if
needed for backwards compatibility reasons)

On 2014-12-19 14:40:14 +0000, Dimitri van Heesch wrote:

inside cref it is easy to add support for &lt; and &gt;
So I'll add that as well (next to the more readable { and })

On 2014-12-25 16:02:56 +0000, Dimitri van Heesch wrote:

This bug was previously marked ASSIGNED, which means it should be fixed in
doxygen version 1.8.9. Please verify if this is indeed the case. Reopen the
bug if you think it is not fixed and please include any additional information 
that you think can be relevant (preferrably in the form of a self-contained example).

On 2015-01-06 17:14:26 +0000, Ben Spiller wrote:

Thanks. This is partly fixed, but also partly worse in 1.8.9 than 1.8.8:

- in 1.8.9 <T>, &lt;T&gtT; and {T} are all now transformed to <T> which is great

- but unlike 1.8.8, in 1.8.9 references to generic TYPES/classes are no longer transformed into links (whichever syntax is used, and regardless of AUTOLINK_SUPPORT setting). i.e. cref="MyGenericMethod{T}(MyGenericType{T})" is correctly transformed to a link to , but cref="MyGenericType{T}" is not transformed to a link (just to the text MyGenericType<T>). 

So there is an important regression from the previous release. It's close though! :)

On 2015-01-06 18:53:40 +0000, Dimitri van Heesch wrote:

Does it work if you use cref="MyGenericType" instead of cref="MyGenericType{T}"? (not saying that is a good solution, but that may gives me a hint where to look).

On 2015-01-08 10:42:02 +0000, Ben Spiller wrote:

It doesn't make a different in 1.8.8, but yes in 1.8.9 the link is generated if you specify cref="MyGenericType" without the {T} argument. 

(btw in some parts of our code we have both a generic and a non generic type  with the same name - which is allowed by .NET, and are treated as separate types - so this wouldn't be a workaround for us. But note I'm seeing the problem even for simpler cases)

Here's the code:

	public class Foo<T>

	/// <summary>
	/// Represents the name and type of a field in an <see cref="EventType"/>.
	/// </summary>
	/// <remarks>
	/// a <see cref="Foo&lt;T&gt"/>
	/// b <see cref="Foo{T}"/>
	/// c <see cref="Foo"/>
	/// d <see cref="Foo<T>"/>
	/// </remarks>
	public class Bar

On 1.8.8, only (d) gets made into a link, in 1.8.9 only (c) gets made into a link. What I expect is for a/b/d (but not c) to be made into links.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment