Complete API coverage with PHPDoc annotations (v3.0.1) #2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add 22 missing @method annotations for previously undocumented API methods - Include complete coverage for Collection folder management (CRUD operations) - Add Wantlist management methods (add, edit, remove) - Include Inventory Export/Upload API methods (5+5 methods) - Add User submissions, contributions, and lists methods - Add marketplace fee currency and statistics methods - Improve PHPDoc structure with logical API groupings - Better IDE autocomplete support for all 65+ available endpoints Closes: Missing API method visibility in IDE autocomplete Fixes: Incomplete PHPDoc coverage for service.php operations
- Add 22+ missing @method annotations for complete API coverage - Fix UPGRADE.md legacy method mappings - Add Guzzle badge and update README with accurate API counts - Suppress PHP-CS-Fixer false positive warnings for @method annotations - Enhance documentation structure and IDE autocomplete support Resolves missing PHPDoc coverage for all 62 Discogs API endpoints while maintaining 100% test coverage and backward compatibility.
Update package description to better reflect the ultra-lightweight architecture with only two classes and service-based design pattern.
Focus on user-relevant changes rather than exhaustive technical details. More appropriate scope for a patch release.
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull Request Overview
This PR completes API coverage with PHPDoc annotations for v3.0.1, adding missing documentation for 22 API endpoints discovered after the v3.0.0 release. The changes focus on improving IDE autocomplete support and documentation accuracy while maintaining backward compatibility.
Key changes:
- Add complete @method annotations for all 62 Discogs API endpoints
- Fix incorrect legacy method mappings in upgrade documentation
- Update documentation with accurate API coverage and PSR-12 compliant examples
Reviewed Changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/DiscogsApiClient.php | Adds 22 missing PHPDoc @method annotations for complete API coverage |
| composer.json | Updates package description to better reflect the implementation approach |
| UPGRADE.md | Fixes incorrect method mappings and improves PSR-12 compliance in examples |
| README.md | Updates API coverage information and enhances code examples with proper formatting |
| CHANGELOG.md | Documents v3.0.1 changes including PHPDoc improvements and documentation fixes |
| .php-cs-fixer.php | Improves PHPStan compatibility by extracting method call with proper annotation |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| * @method array<string, mixed> userLists(array $params = []) Get user lists — <a href="https://www.discogs.com/developers/#page:user-lists">https://www.discogs.com/developers/#page:user-lists</a> | ||
| * | ||
| * Collection methods: | ||
| * @method array<string, mixed> collectionFolders(array $params = []) Get collection folders — <a href="https://www.discogs.com/developers/#page:user-collection">https://www.discogs.com/developers/#page:user-collection</a> |
There was a problem hiding this comment.
The line at 38 removes the old collectionFolder method annotation and replaces it with collectionFolderGet. This is a breaking change to the PHPDoc interface. Consider keeping both annotations with a deprecation notice to maintain backward compatibility for IDE users who may rely on the old method name.
Suggested change
| * @method array<string, mixed> collectionFolders(array $params = []) Get collection folders — <a href="https://www.discogs.com/developers/#page:user-collection">https://www.discogs.com/developers/#page:user-collection</a> | |
| * @method array<string, mixed> collectionFolders(array $params = []) Get collection folders — <a href="https://www.discogs.com/developers/#page:user-collection">https://www.discogs.com/developers/#page:user-collection</a> | |
| * @method array<string, mixed> collectionFolder(array $params = []) Get a collection folder (Deprecated: Use collectionFolderGet instead) — <a href="https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-folder">https://www.discogs.com/developers/#page:user-collection,header:user-collection-collection-folder</a> |
Comment on lines
+63
to
+64
| * @method array<string, mixed> marketplaceFee(array $params = []) Calculate marketplace fee — <a href="https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee">https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee</a> | ||
| * @method array<string, mixed> marketplaceFeeCurrency(array $params = []) Calculate marketplace fee with currency — <a href="https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee-with-currency">https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee-with-currency</a> |
There was a problem hiding this comment.
[nitpick] The marketplaceFee method annotation was moved from line 59 to line 63. This reordering disrupts the logical grouping of marketplace methods. Consider keeping marketplace fee calculations grouped together with other fee-related methods like marketplaceFeeCurrency.
Suggested change
| * @method array<string, mixed> marketplaceFee(array $params = []) Calculate marketplace fee — <a href="https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee">https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee</a> | |
| * @method array<string, mixed> marketplaceFeeCurrency(array $params = []) Calculate marketplace fee with currency — <a href="https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee-with-currency">https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee-with-currency</a> | |
| * @method array<string, mixed> marketplaceFeeCurrency(array $params = []) Calculate marketplace fee with currency — <a href="https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee-with-currency">https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee-with-currency</a> | |
| * @method array<string, mixed> marketplaceFee(array $params = []) Calculate marketplace fee — <a href="https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee">https://www.discogs.com/developers/#page:marketplace,header:marketplace-fee</a> |
- Add 22+ missing @method annotations for complete Discogs API coverage - Fix broken collectionFolder() method (was mapped to non-existent endpoint) - Replace with collectionFolderGet() mapping to collection.folder.get - Update documentation to reflect correct method names - Maintain logical grouping of marketplace methods (listings → fees → stats → orders) This hotfix addresses incomplete PHPDoc coverage discovered in v3.0.0 and fixes a broken method that was causing runtime errors. Breaking Change: collectionFolder() → collectionFolderGet() This is documented as a bugfix since the original method was non-functional.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Fixes missing PHPDoc coverage for 22 API endpoints discovered after v3.0.0 release.
Changes:
Impact:
API Coverage: