Skip to content

Add/improve javadocs for interface classes#973

Merged
Avery-Dunn merged 1 commit intodevfrom
avdunn/add-missing-javadocs
Jul 21, 2025
Merged

Add/improve javadocs for interface classes#973
Avery-Dunn merged 1 commit intodevfrom
avdunn/add-missing-javadocs

Conversation

@Avery-Dunn
Copy link
Copy Markdown
Contributor

@Avery-Dunn Avery-Dunn commented Jul 14, 2025

Begins the work described in #971

This PR fills documentation gaps and improves existing documentation to all interfaces in the library. The changes exclusively affect Javadoc comments, so there are no changes to the actual behavior of any API.

This PR is also a trial run of the new agent feature in IntelliJ's Copilot plugin:

  • All of the changes were manually reviewed to ensure MSAL behavior was described accurately
  • With few exceptions, the prompts produced accurate descriptions on the first try without being given any context about MSAL's actual behavior
    • For the most part, I simply told it to review all interfaces with missing/poor documentation, list them based on quality, then told it to add/improve a few filenames at a time
  • The few mistakes it did make were easily corrected by a follow-up prompt describing what was wrong
    • As an example, it incorrectly implied that "scopes" API was just for Graph resources (likely because many of our tests use Graph), and I just had to tell it to give a more generic description

@Avery-Dunn Avery-Dunn requested a review from a team as a code owner July 14, 2025 01:05
* Various parameter classes in the library implement this interface to provide a consistent way to
* configure token requests.
*/
interface IAcquireTokenParameters {
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: strange that you went with interface for this. new field -> broken interface.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was before my time here so I don't know why it's an interface.

But it's not public, so if we did add something it wouldn't be a breaking change for customers since they could only see our implementations anyway (it would be the same as adding a new public API to any class).

@Avery-Dunn Avery-Dunn merged commit 4e7c182 into dev Jul 21, 2025
5 checks passed
@Avery-Dunn Avery-Dunn deleted the avdunn/add-missing-javadocs branch September 15, 2025 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants