Skip to content

chore: update pdc docs #620

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 13 commits into
base: main
Choose a base branch
from

Conversation

Timongcraft
Copy link
Contributor

@Timongcraft Timongcraft commented Jul 5, 2025

  • Refactor examples to use ItemStack instead of ItemMeta
  • Cleanup for PDC docs

Copy link

github-actions bot commented Jul 5, 2025

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name Status Preview Last Commit
papermc-docs ✅ Ready (View Log) Visit Preview 272c798

Copy link
Contributor

@Strokkur424 Strokkur424 left a comment

Choose a reason for hiding this comment

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

In general I think you could provide more JavaDoc links here and there

@Timongcraft Timongcraft force-pushed the chore/update-pdc-docs branch from b6bc21d to fb56eef Compare July 5, 2025 13:10
@Timongcraft
Copy link
Contributor Author

In general I think you could provide more JavaDoc links here and there

As I see it the docs only link to stuff one timer per document and I think that is fine

@Timongcraft
Copy link
Contributor Author

ahhh, you can't use double underline?

```

:::


## Read-only containers
Copy link
Member

Choose a reason for hiding this comment

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

this should be just an aside

Suggested change
## Read-only containers

Copy link
Contributor Author

Choose a reason for hiding this comment

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

No, because then it wouldn't be in the sidebar

Copy link
Member

Choose a reason for hiding this comment

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

if it's supposed to be a full-fledged section, it should elaborate on the purpose and benefit of accessing a view instead of a mutable version in general, not just a single note that duplicates information from the "Storing on different objects" section

Copy link
Contributor Author

Choose a reason for hiding this comment

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

it should elaborate on the purpose and benefit of accessing a view instead of a mutable version in general
What should I elaborate on (other than not accidentally modifying the data)?
Also there's no "benefit", it is just that you can't get a normal container from e.g. an OfflinePlayer.

Copy link
Member

Choose a reason for hiding this comment

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

well currently the purpose of the view is to side-step technical limitations, like the ItemMeta snapshot costliness or the file I/O intensity of having a mutable offline player PDC, which is pretty noteworthy

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Alright, is this good then?

Timongcraft and others added 3 commits July 6, 2025 13:33
fix: javadoc links

Co-authored-by: Matouš Kučera <[email protected]>
@Timongcraft Timongcraft force-pushed the chore/update-pdc-docs branch from e8566ba to bb725f5 Compare July 6, 2025 11:39
@@ -178,6 +224,19 @@ E.g. Placing an ItemStack as a Block (with a TileState) ***does not*** copy over
Objects that can have a PDC implement the [`PersistentDataHolder`](jd:paper:org.bukkit.persistence.PersistentDataHolder) interface
and their PDC can be fetched with [`PersistentDataHolder#getPersistentDataContainer()`](jd:paper:org.bukkit.persistence.PersistentDataHolder#getPersistentDataContainer()).

- ##### [`ItemStack`](jd:paper:org.bukkit.inventory.ItemStack)
Copy link
Contributor

Choose a reason for hiding this comment

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

This now feels kinda redundant with the adding data section, might just link that part of the page in the above section and drop the 1.20.4 compat (which add a bit of complexity to the page). Same for the getting data section imo that part is too complex and should show a simple use case (like the world for example) for newbie and then expand on the read only view like you already did.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

This has a bit of extra info though and I don't get why you wouldn't want compat for old versions? Also in the "adding data" section the "getting data" for a world is already included, so I thought explaining the view stuff here would be a good idea. But do you think there should just be an extra example of the world first or what exactly do you mean?

chore: compact example code
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.

6 participants