ADDITIONAL SYSTEM INFORMATION :
openjdk 17.0.4 2022-07-19
OpenJDK Runtime Environment Temurin-17.0.4+8 (build 17.0.4+8)
OpenJDK 64-Bit Server VM Temurin-17.0.4+8 (build 17.0.4+8, mixed mode, sharing)

A DESCRIPTION OF THE PROBLEM :
Please improve Javadoc so that if a constructor is provided for a record, for each missing `@param` Javadoc will use the `@param` provided in the record description. This is analogous to how Javadoc already copies method API documentation for a method `@Override` if no documentation is given.

Consider the following Java record, with documentation for each record component:

```java
/**
 * Foo bar record.
 * @param foo That foo thing; cannot be <code>null</code>.
 * @param bar That bar thing; cannot be <code>null</code>.
 */
public record FooBar(String foo, String bar) {
}
```

Java will automatically generate a `FooBar` constructor. In addition Javadoc will automatically copy the record `@param` documentation to the constructor. This works fine.

However it is extremely likely that one will need to validate and normalize arguments, necessitating the addition of a custom constructor:

```java
/**
 * Foo bar record.
 * @param foo That foo thing; cannot be <code>null</code>.
 * @param bar That bar thing; cannot be <code>null</code>.
 */
public record FooBar(String foo, String bar) {

  /** Constructor for argument validation and normalization. */
  public FooBar {
    Objects.requireNonNull(foo);
    Objects.requireNonNull(bar);
  }

}
```

Unfortunately in this case Javadoc no longer copies the `@param` documentation, and worse, `-Xdoclint:all` issues a warning:

```
[WARNING] Javadoc Warnings
[WARNING] …/FooBar.java:xx: warning: no @param for foo
[WARNING] public FooBar {
[WARNING] ^
[WARNING] …/FooBar.java:xx: warning: no @param for bar
[WARNING] public FooBar {
[WARNING] ^
[WARNING] 2 warnings
```

The problem is not with linting or warnings; the problem is that Javadoc did not copy over the `@param` documentation as it did with the generated constructor. This forces the developer to copy and paste needlessly:

```java
/**
 * Foo bar record.
 * @param foo That foo thing; cannot be <code>null</code>.
 * @param bar That bar thing; cannot be <code>null</code>.
 */
public record FooBar(String foo, String bar) {

  /**
   * Constructor for argument validation and normalization.
   * @param foo That foo thing; cannot be <code>null</code>.
   * @param bar That bar thing; cannot be <code>null</code>.
   */
  public FooBar {
    Objects.requireNonNull(foo);
    Objects.requireNonNull(bar);
  }

}
```

In other words, records are now forcing boilerplate upon the developer, when their purpose is to reduce boilerplate.

An analogous situation which Javadoc (now) handles correctly is when overriding methods. A developer may leave off documentation for a method annotated with `@Override`, and Javadoc will copy over the documentation from the overridden class or interface. In this case there is no need for an `@Override` annotation, as the semantics are implicit by the context.

Javadoc provides an `{@inheritDoc}` mechanism for when the developer wants to duplicate the documentation for an overridden method and then add to it. Perhaps Javadoc might provide a `{@defaultDoc}` or `{@recordDoc}` or some similar mechanism to add to the record-level documentation.

Still by default, if no documentation at all is provided for a custom constructor, Javadoc should copy over the record-level `@param` documentation as it does already if no custom constructor is provided, and emit no doclint warning.