Skip to content

Rework how common libraries are included in Javadoc #39735

Open
@alzimmermsft

Description

@alzimmermsft

Currently, to have Javadocs properly include Javadocs from inherited methods, we use Maven Javadocs's sourcepath and excludePackageNames settings to include source code of common libraries, that will have the inherited Javadocs and help generate links approriately.

https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/parents/azure-client-sdk-parent/pom.xml#L241

While this works in most cases, this breaks down around release time when some libraries may have shipped and others haven't. For example, when azure-core added a dependency on azure-xml, before azure-core shipped downstream libraries were still referencing the released version. So, Javadoc had a case where azure-core source code was referenced, having Javadoc using azure-xml, but there was no dependency on azure-xml resulting in Javadoc not being able to find the azure-xml classes, failing Javadoc.

The configuration is brittle and should be reworked so that we only reference released libraries in Javadocs so downstream libraries don't begin failing Javadoc generation when a release scenario like above happens.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ClientThis issue points to a problem in the data-plane of the library.EngSysThis issue is impacting the engineering system.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions