Skip to content
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

Add support for XML documentation in the generator #17397

Closed
rolfbjarne opened this issue Jan 30, 2023 · 1 comment · Fixed by #20253
Closed

Add support for XML documentation in the generator #17397

rolfbjarne opened this issue Jan 30, 2023 · 1 comment · Fixed by #20253
Assignees
Labels
documentation The issue or pull request is about documentation dotnet An issue or pull request related to .NET (6) generator Issues affecting the generator
Projects
Milestone

Comments

@rolfbjarne
Copy link
Member

rolfbjarne commented Jan 30, 2023

Ref: #14372, step 4

The idea is to add support in the generator for writing XML documentation based on an attribute in the api definition:

This would be the attribute:

public class DocumentationAttribute : Attribute {
    public DocumentationAttribute ()
    {
    }

    public DocumentationAttribute (string xml)
    {
        this.Xml = xml;
    }
 
    public string Xml { get; set; }
    public string Include { get; set; }
    public string XmlPath { get; set; }
}

and this would be how to use it:

[Documentation (
@"
/// <summary>
/// Documentation for UIView
/// </summary>
")
]
public interface UIView {
}

[Documentation (Include = "/path/to/file.xml", XmlPath = "Type@[FullName='UIKit.UIView']/Docs/*")]
public interface UIView {
}

MAUI example with include path: https://github.com/dotnet/maui/blob/6377c3259387913f3acc7f7858028f7c97a0480b/src/Controls/src/Core/Application.cs#L17

@rolfbjarne rolfbjarne added generator Issues affecting the generator dotnet An issue or pull request related to .NET (6) labels Jan 30, 2023
@rolfbjarne rolfbjarne added this to the .NET 8 milestone Jan 30, 2023
@rolfbjarne rolfbjarne added this to Documentation in .NET 8 - Themes Jan 30, 2023
@rolfbjarne rolfbjarne added the documentation The issue or pull request is about documentation label Jan 30, 2023
@rolfbjarne rolfbjarne removed this from Documentation in .NET 8 - Themes Sep 8, 2023
@rolfbjarne rolfbjarne modified the milestones: .NET 8, .NET 9 Sep 8, 2023
@rolfbjarne rolfbjarne added this to Documentation in .NET 9 Sep 8, 2023
@rolfbjarne rolfbjarne self-assigned this Mar 4, 2024
@rolfbjarne
Copy link
Member Author

It seems we don't need an additional attribute, we can just write normal xml docs:

/// <summary>Summar of SomeType</summary>
[BaseType (typeof (NSObject)]
interface SomeType {}

it's possible to load the xml doc in the generator and forward it to the generated code.

rolfbjarne added a commit to rolfbjarne/xamarin-macios that referenced this issue Mar 5, 2024
rolfbjarne added a commit that referenced this issue Mar 13, 2024
…ixes #17397. (#20253)

* Enable generation of the documentation file (.xml) by the C# compiler when building projects (by passing the `DocumentationFlag` argument to the Csc task).
	* Also disable the CSC1591 warning, which complains about having public APIs without xml documentation; it just turns out to be annoying rather than helpful, since most APIs won't be documented.
* Add support in the generator for reading the .xml file next to the compiled api definition assembly, and then looking for documentation there when generating binding code.
	* When enabled, enable generation of the documentation file if the generator is compiling the api definitions.
	* Make it an opt-out, in case the new code causes problems.
* Add tests. 

Fixes #17397.

---------

Co-authored-by: Haritha Mohan <[email protected]>
.NET 9 automation moved this from Documentation to Done Mar 13, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation The issue or pull request is about documentation dotnet An issue or pull request related to .NET (6) generator Issues affecting the generator
Projects
1 participant