doxygen

doxygen copied to clipboard

status RESOLVED severity normal in component general for --- Reported in version 1.5.3-SVN on platform Other Assigned to: Dimitri van Heesch

On 2007-03-28 15:22:23 +0000, Jürgen Bayer wrote:

C#'s seealso are missing in the created documentation

On 2007-06-04 19:55:34 +0000, Dimitri van Heesch wrote:

Can you provide an example, so I can verify if this is fixed along with the other C# see related fixes?

On 2009-01-19 18:43:19 +0000, Christoph Wurm wrote:

Closing this bug report as no further information has been provided. Please feel free to reopen this bug if you can provide the information asked for. Thanks!

I'm providing some examples. Currently, with 1.9.3, the links to the members are not created properly. I've whipped up a sample that I've could think of as a typical use-case of the seealso tag. The following sample can go in one file.

using Other.Name.Space

namespace My.Name.Space
{
    public class MyClass
    {
        /// <summary>Place holder</summary>
        /// <remarks>Place holder documentation to make it possible to make the link</remarks>
        public EventHandler MyEvent;

        /// <summary>This is the member providing a demo for the <c>seealso</c> tag.</summary>
        /// <seealso cref="MyEvent"/>
        /// <seealso cref="MyEnum"/>
        /// <seealso cref="MyEnum.MyValue"/>
        /// <seealso cref="TheirClass.SomeMethod()"/>
        public void Method() { }
    }

    /// <summary>Place holder</summary>
    /// <remarks>Place holder documentation to make it possible to make the link</remarks>
    public enum MyEnum
    {
        /// <summary>Place holder</summary>
        MyValue,
    }
}

namespace Other.Name.Space
{
    /// <summary>Place holder</summary>
    /// <remarks>Place holder documentation to make it possible to make the link</remarks>
    public class TheirClass
    {
        /// <summary>Place holder</summary>
        /// <remarks>Place holder documentation to make it possible to make the link</remarks>
        public void SomeMethod() { }
    }
}

I've just looked up how the XML tag is specified, and it apparently supports specifying custom link text in the content of the tag, while also supporting links to other URL, like so:

/// <seealso href="link">Link Text</seealso>

I was not aware of that, up until now. I do not know if cref+"Link Text" works, but would not be surprised if it does.

The seealso tag in C# has 2 definitions:

/// <seealso cref="member"/>

and

/// <seealso href="link">Link Text</seealso>

When looking at the code I see that for the seealso only the cref is supported and not the href. In the original standard (and still the only official standard as far as I know, though at some places the mentioned page is also regarded as standard) only the cref was mentioned and hence the href is not supported in the current doxygen version.

I've later read that Doxygen follows the ECMA-334 standard, but did not wanted to spam the comments with apologies, rather I wanted to read more on the topic before coming back; sorry about that.

The 6th edition does mention the href attribute (was not aware of it before) but from the provided example I could understand why some of these tags not fully implemented.

Regardless, I believe it is a good idea to read the MS Docs in conjunction with ECMA-334 so it becomes clearer what they want to achieve, and a documentation on a class also shows what output they intended together with the reference source could help?

Looks like after numerous years a new version of the C# Language Definition (Standard ECMA-334 6th Edition i.e. https://www.ecma-international.org/wp-content/uploads/ECMA-334_6th_edition_june_2022.pdf) has been released.