doxygen
[Enhancement] .NET documentation: take .XML documentation files accompanying assemblies as input.
When .NET assemblies are generated, they are usually accompanied by .xml files that contain associated documentation. Softwares exist that take these files as input to generate html and/or chm documentation (Sandcastle, for example). It would be a great enhancement for Doxygen if it could do the same.
EDIT:
The .NET XML documentation files that we are speaking about are the ones automatically generated by Visual Studio when including that line inside a PropertyGroup element inside a project file:
<GenerateDocumentationFile>true</GenerateDocumentationFile>
An example of a full working .csproj file with that feature:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net6.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>
</Project>
The contents of such a file follow the same standard than in usual XML comments inside .NET source code as far as we know, with some necessary additions. Here is an example:
<?xml version="1.0"?>
<doc>
<assembly>
<name>MyNetLib</name>
</assembly>
<members>
<member name="T:MyNetLib.MyNetClass">
<summary>
This class performs an important function.
</summary>
</member>
<member name="M:MyNetLib.MyNetClass.#ctor">
<summary>
A simple class!
</summary>
<remarks>
This is the constructor for the example class.
</remarks>
</member>
<member name="M:MyNetLib.MyNetClass.MyFunction(System.Int64)">
<summary>
A function that prints a number on console...
</summary>
<remarks>
This is a function that prints a number on console!
</remarks>
<param name="nb">the number to print.</param>
</member>
</members>
</doc>
Here is an archive that gives an example of a .NET project that generates such files and how Doxygen could handle them:
(We currently use Doxygen 1.13.2 for our works, but no actual run of Doxygen was necessary here since by definition at the present time trying to run Doxygen with a .NET XML doc file as input cannot succeed)
As normal C++ projects don't have assemblies or associated xml files with documentation (in general I think it is bad to have documentation and source code in different files as they might diverge quite fast) it is unknown how such an associated file would look like.
- Is there some official standard for this type of documentation?
Furthermore
- Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the enhancement request? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).
- Please also specify the full doxygen version used (doxygen -v).
I edited my previous message with that further information that you requested!
So, when I understand it correctly, the xml file (MyNetLib.xml) has the same elements in the documentation as as the, original, source code (MyNetClass.cs) which should follow the ECMA-334 standard. The xml file contains the names of the entities (classes / functions, ...) and based on this the documentation should be generated.
Furthermore the xml file is generated from the original source code files.
What I don't understand is: why not use the original source code (cs file ) to generate the documentation?
The main reason is that in the end you have the same documentation with the same format independently of the language of your code (C#, C++/CLI, F#, etc; every language available on the .NET platform). That feature would solve all the problems that I have reported in this issue: https://github.com/doxygen/doxygen/issues/11498
Doxygen doesn't support F# so this would anyway require another approach. Doxygen can also output XML as output format, did you have a look at that possibility?
Please note that when taking as input the auto-generated XML documentation, Doxygen would not even know (and would not need to) in which language the code was originally written.
We know that Doxygen can output XML files, we actually use that at some point during our .NET wrapping process. But I do not see how that could help here, unless some other software exists that takes this output as input for generating documentation (since we still want html/chm at the final output). And that would not interest us very much: for more context about this request, the old way we used (and still use) for our .NET documentation was by giving the auto-generated XML output as input to Sandcastle which then proceed to the actual generation of documentation. Our purpose here is to remove Sandcastle from our process and thus rely only on Doxygen, because we basically want to have one less tool/dependency. Thus, so we have no incentive to use a solution that would have Doxygen's XML output as an intermediate step.