dotnet / dotnet/docfx

[Feature Request] Filter extension method usages, but not definitions

Open
#8,575 0 comments 0 reactions 0 assignees View on GitHub
dotnet: api-filter
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 11m
Merged PRs (30d)
10

Description

I have unconstrained generic extension methods, meaning they apply to every instance class:
```c#
namespace MyCoolLib;

public static class ObjectExtensions
{
///Rate an object
public static int RateObject(this T o)
{
return 42;
}

///Rate a collection of objects
public static int RateObjects(this IEnumerable objects)
{
return objects.Sum(o => o.RateObject());
}
}
```

I also have many instance classes implicitly inheriting from `System.Object`:
```c#

///A Foo object
public class Foo /* : object */
{
}
```

I want my documentation to:
1. Contain the information about the `ObjectExtensions.RateObject()` extensions, providing the user with "Rate an object" and "Rate a collection of objects" documentation.
2. _Not_ contain the extension methods on every instance class in my assemblies.

I can filter the entire extension method:

```yaml
apiRules:
- exclude:
uidRegex: MyCoolLib\.ObjectExtensions\.RateObject
type: Method
```

But this doesn't fulfill #1, it hides the documentation for the methods themself as well.

## Alternative 1: filter methods by a new type ExtensionMethod
A new filter type: "ExtensionMethod", which will filter matches when _used as_ extension method:

```yaml
apiRules:
- exclude:
uidRegex: MyCoolLib\.ObjectExtensions\.RateObject
type: ExtensionMethod
```

## Alternative 2: filter extension methods by invocation
Filter all extension method invocations on types, like this:

```yaml
apiRules:
- exclude:
uidRegex: MyCoolLib\.ObjectExtensions\.RateObject``1\(MyCoolLib
type: Method
- exclude:
uidRegex: MyCoolLib\.ObjectExtensions\.RateObjects``1\(System.Collections.Generic.IEnumerable{MyCoolLib
type: Method
```

Adding `&& _filter.IncludeApi(reduced)` here will allow that:

https://github.com/dotnet/docfx/blob/905a0fd55ba6299767b3ce0bb8d3f92bb7a16cb8/src/Microsoft.DocAsCode.Dotnet/Visitors/SymbolVisitorAdapter.cs#L644-L650

But the ids aren't translated that way (see: "``1" and "{"). The ids are translated below that code, but the result of that translation is a string, while `IncludeApi()` wants an `ISymbol`...

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.