Skip to content

docs: Update documentation for controller PR #1723#47

Closed
tarrencev wants to merge 1 commit intomainfrom
docs-update-1750863747
Closed

docs: Update documentation for controller PR #1723#47
tarrencev wants to merge 1 commit intomainfrom
docs-update-1750863747

Conversation

@tarrencev
Copy link
Contributor

This PR updates the documentation to reflect changes made in cartridge-gg/controller#1723

**Original PR Details:**
- Title: feat: add listing action from collection pages
- Files changed: examples/next/src/components/Profile.tsx

packages/keychain/src/components/connect/create/useCreateController.ts
packages/keychain/src/utils/controller.ts
packages/profile/package.json
packages/profile/src/components/achievements/index.tsx
packages/profile/src/components/app.tsx
packages/profile/src/components/inventory/collection/collectible-asset.tsx
packages/profile/src/components/inventory/collection/collectible.tsx
packages/profile/src/components/inventory/collection/collection-asset.tsx
packages/profile/src/components/inventory/collection/collection-listing.tsx
packages/profile/src/components/inventory/collection/collection-purchase.tsx
packages/profile/src/components/inventory/collection/collection.tsx
packages/profile/src/components/inventory/collection/collections.tsx
packages/profile/src/components/inventory/collection/header.tsx
packages/profile/src/components/inventory/collection/index.ts
packages/profile/src/components/inventory/collection/send/collection.tsx
packages/profile/src/components/inventory/collection/send/header.tsx
packages/profile/src/components/inventory/index.tsx
packages/profile/src/components/provider/data.tsx
packages/profile/src/components/provider/index.tsx
packages/profile/src/components/provider/marketplace.tsx
packages/profile/src/context/marketplace.ts
packages/profile/src/hooks/collection.ts
packages/profile/src/hooks/entrypoints.ts
packages/profile/src/hooks/marketplace.ts
packages/profile/src/hooks/token.ts
packages/profile/src/hooks/traceabilities.ts
pnpm-lock.yaml
pnpm-workspace.yaml

Please review the documentation changes to ensure they accurately reflect the controller updates.

    Updates documentation to reflect changes made in:
    feat: add listing action from collection pages

    Related controller PR: cartridge-gg/controller#1723
@vercel
Copy link

vercel bot commented Jun 25, 2025

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name Status Preview Updated (UTC)
docs ✅ Ready (Inspect) Visit Preview Jun 25, 2025 3:05pm

@claude
Copy link
Contributor

claude bot commented Jun 25, 2025

Claude finished @tarrencev's task —— View job


PR Review Complete ✅

Review Tasks

  • Read and analyze inventory.md changes
  • Review new marketplace.md documentation
  • Check vocs.config.ts navigation updates
  • Assess documentation quality and completeness
  • Provide comprehensive feedback

📋 Review Summary

This PR adds comprehensive marketplace documentation to reflect the new NFT listing functionality from controller PR #1723. The documentation is well-structured and thorough, but there are several areas for improvement.

✅ Strengths

Documentation Quality:

  • Excellent comprehensive coverage of marketplace features
  • Well-organized structure with logical progression from listing → purchasing → management
  • Good balance of high-level concepts and detailed implementation
  • Includes troubleshooting section and best practices

Technical Accuracy:

  • API usage is consistent with existing patterns (openProfile usage matches achievements:integration.md:42)
  • TypeScript examples are properly typed
  • Configuration examples align with existing Controller setup patterns

User Experience:

  • Clear step-by-step instructions for both sellers and buyers
  • Good visual hierarchy with proper markdown formatting
  • Seamless integration with existing inventory documentation
  • Proper cross-referencing between inventory and marketplace docs

⚠️ Issues & Improvements

1. API Consistency Questions

marketplace.md:159 - The import path seems incomplete:

import { useMarketplace } from "@cartridge/marketplace";

Recommendation: Verify this import path exists. Should it be @cartridge/controller or a different package?

2. Code Example Inconsistency

marketplace.md:149-151 - The openProfile signature with options:

controller.openProfile("inventory", {
  contractAddress: "0x1234...",
});

Issue: This extended signature isn't documented elsewhere and may not exist.
Recommendation: Either document this API or remove the example if it's not implemented.

3. Technical Specification Gaps

Fee Structure Details:

  • The fee percentages (1.0% marketplace, 1.0% royalty) in the example may not be accurate
  • No mention of how fees are determined or if they're configurable

Contract Integration:

  • Missing information about which smart contracts handle marketplace operations
  • No mention of required contract approvals or gas considerations

4. Documentation Structure

marketplace.md length: At 313 lines, this is quite comprehensive but might benefit from being split into multiple focused pages:

  • Basic marketplace usage
  • Advanced features and configuration
  • API reference and troubleshooting

5. Missing Examples

Real-world Integration:

  • No concrete examples linking to actual implementations (unlike achievements which references DopeWars)
  • Could benefit from a working example repository or code sandbox

6. Configuration Verification

Token Contracts (marketplace.md:208-209):

"erc20:0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", # ETH
"erc20:0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d", # STRK

Recommendation: Verify these contract addresses are correct for the intended network.

🔧 Minor Issues

  1. inventory.md:83 - Link formatting should be consistent: /controller/marketplace vs other internal links
  2. marketplace.md:100 - ERC-2981 standard mentioned but not linked to specification
  3. marketplace.md:280-311 - API reference types should be verified against actual implementation

🎯 Recommendations

High Priority

  1. Verify API imports and signatures - Ensure all code examples work with actual controller implementation
  2. Validate contract addresses - Confirm token contract addresses are correct
  3. Test documentation flow - Walk through the entire marketplace flow to ensure accuracy

Medium Priority

  1. Add real-world examples - Include links to actual implementations
  2. Consider documentation split - Break down the large marketplace.md file
  3. Add gas estimation guidance - Include typical gas costs for marketplace operations

Low Priority

  1. Enhanced troubleshooting - Add more specific error scenarios
  2. Performance considerations - Document bulk operation limits
  3. Mobile UX notes - Add any mobile-specific marketplace considerations

📊 Overall Assessment

Quality Score: 8/10

  • Comprehensive coverage ✅
  • Good user experience ✅
  • Technical accuracy needs verification ⚠️
  • Could benefit from splitting and more examples 💡

The documentation successfully covers the marketplace functionality and provides a solid foundation for users. The main concerns are around verifying technical accuracy and ensuring all code examples work with the actual implementation.


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.

1 participant