micrometer-metrics / micrometer-metrics/micrometer-docs-generator

Match sub-classing interfaces

Open
#338 5 comments 0 reactions 0 assignees View on GitHub
enhancement good first issue help wanted
Dominant language
Java
Stars
18
Forks
15
Avg merge
2m
Merged PRs (30d)
6

Description

# Description

We use `MeterDocumentation` with enums to document our metrics, and generally quite like the pattern, as it provides some technical documentation for all our metrics. We extend `MeterDocumentation` however to add more information. While it would be nice to have that shown by the generator, this is not the problem.

The main issue is that the generator doesn't pick up enums implementing the extending interface, it only picks up enums which directly implement `MeterDocumentation`.

Take the following `ExtendedMeterDocumentation` interface:

```java
/**
* Extends the base {@link MeterDocumentation} API to allow for more static description, e.g.
* help/description associated with a given metric.
*/
public interface ExtendedMeterDocumentation extends MeterDocumentation {
final Duration[] EMPTY_SLOS = new Duration[0];

/** Returns the description (also known as {@code help} in some systems) for the given meter. */
String getDescription();

/**
* Returns the buckets to be used if the meter type is a {@link Meter.Type#TIMER} or {@link
* Meter.Type#DISTRIBUTION_SUMMARY}.
*/
default Duration[] getServiceLevelObjectives() {
return EMPTY_SLOS;
}
}
```

And the following enum:

```java
public enum MyMetrics implements ExtendedMeterDocumentation {
// ... some metrics
}
```

Naively, I would expect the generator to pick up `MyMetrics`, but it does not.

As a workaround, I can do the following:

```java
public enum MyMetrics implements MeterDocumentation, ExtendedMeterDocumentation {
// ... some metrics
}
```

Then the generator will pick it up. It would be great though if it wasn't necessary to again declare the implementation of `MeterDocumentation`.

I'm happy to pick this up if you think this would be valuable. I understand there's not much urgency if there is a workaround :)

Contributor guide

Open the contributing guide

Research direction

No files or tests are named in the issue. Start by tracing the generator's detection of enums implementing MeterDocumentation, then compare direct implementation with the ExtendedMeterDocumentation example; done means MyMetrics is discovered without redeclaring MeterDocumentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.