Skip to content

Docs: note ClassPath.getResources keeps one entry per path - #8608

Open
Hashim1999164 wants to merge 1 commit into
google:masterfrom
Hashim1999164:docs/classpath-getresources-duplicate-paths-2712
Open

Docs: note ClassPath.getResources keeps one entry per path#8608
Hashim1999164 wants to merge 1 commit into
google:masterfrom
Hashim1999164:docs/classpath-getresources-duplicate-paths-2712

Conversation

@Hashim1999164

@Hashim1999164 Hashim1999164 commented Aug 13, 2026

Copy link
Copy Markdown

Summary

Fixes #2712

Clarifies ClassPath.getResources() so callers know that ResourceInfo equality is by resource name and class loader, and that the returned ImmutableSet therefore keeps only one resource for a given path even when that path appears in multiple jars or directories.

Test plan

  • Review the updated getResources Javadoc
  • Confirm no code behavior changes

@cpovirk cpovirk added type=api-docs Change/add API documentation package=reflect P3 no SLO labels Aug 15, 2026

@MuhammadNiazAli MuhammadNiazAli left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Yeh naya repo/PR hai google/guava #8608 (abhi tak Open hai, achha hai review submit ho sakega). Chaliye review likhte hain:

Review:

This is a small but genuinely useful doc fix clarifying getResources()'s dedup behavior can save someone real debugging time if they assumed every resource on the classpath shows up in the result.

Removing "all" from the first line: Good catch. The old wording "Returns all resources loadable..." — was misleading precisely because the method does not return every resource; it keeps only one entry per path. Dropping "all" makes the opening line accurate instead of contradicting the new paragraph you added right below it.
New paragraph is clear and specific: "instances are equal when they share the same resource name and ClassLoader... only one resource is kept for a given path even if that path appears in multiple jars or directories" this explains both why (equality based on name + ClassLoader) and what the practical effect is (last-one-wins-ish dedup across jars). That's exactly the kind of detail that's easy to discover the hard way and hard to find in existing docs.
One small thing worth checking: since dedup is based on equality of ResourceInfo (name + ClassLoader), it might be worth a one-line note on which entry wins when the same path appears in multiple jars (first one found on the classpath order, presumably) this could matter for someone debugging a "which jar's resource am I actually getting" issue. Not blocking, but it's the natural next question a reader would have after this paragraph.
Scope is right: pure Javadoc change, one file, no logic touched exactly what a "Docs:" prefixed PR should be.

Nit aside, this is a solid, well-scoped documentation clarification. Looks good to approve.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P3 no SLO package=reflect type=api-docs Change/add API documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation of ClassPath#getResources() is misleading

3 participants