Data Docs 2.0 #331
Data Docs 2.0 #331
Conversation
- Overview / Glossary - Token API
ghost
self-assigned this
|
A preview for this pull request is available at https://cdn.rawgit.com/Spongy/SpongeDocs-PRs/e6c31adf/index.html. Here are some links to the pages that were modified:
Since the preview frequently changes, please link to this comment, not to the direct url to the preview. |
Tzky
added
input wanted
|
|
||
| public void swapHealth(DataHolder targetA, DataHolder targetB) { | ||
| if (targetA.supports(HealthData.class) && targetB.supports(HealthData.class)) { | ||
| HealthData healthA = targetA.get(HealthData.class).orNull(); |
There was a problem hiding this comment.
If you have the guarantee, use get() instead of orNull().
|
Since this now explains the core features of the Data API, it is best gotten out as soon as possible. Therefore I'll open it up for review and nitpicking, additional stuff (like Serialization) can be included later. @gabizou Go wild, if you have the time @ the rest, please help me make sure that these docs are as understandable as they need to be |
| Property | ||
| ~~~~~~~~ | ||
|
|
||
| A property is a read-only point of data. It provides information that is directly derived from its holders type, |
There was a problem hiding this comment.
"holders" --> "holder's"
| ======================================= | ||
|
|
||
| To every data manipulator, there is a matching ``ImmutableDataHolder``. For instance both ``HealthData`` and | ||
| ``ImmutableHealthData`` contain the same data, only the latter does not provide any means to make alterations to |
There was a problem hiding this comment.
"only" --> "but" (just sounds better to me, you may disagree)
- Fixed various small problems pointed out by @RobertHerhold - use get() instead of getOrNull() for consistency - consistency in Code Example heading
| First we need to check if our target has health data. We do so by first asking it to provide us with its health | ||
| data by passing its class to the ``getOrCreate()`` method. We get an ``Optional`` which we can use for our check. | ||
| If the target does not support health data, it will be absent. But if the health data is present, it now contains | ||
| a mutable copy of the data present on the data holder. We make our alterations and finally offer the changed data |
There was a problem hiding this comment.
Don't forget to include that if the data is "supported" but not available, it is still created. (the whole point of getOrCreate() versus get()).
- worked braindump into description of data and properties - made descriptions of code examples match the code and vice versa - 'value container' -> 'keyed value' - several small fixes based on gabizous suggestions
- Overview / Glossary - Value API - DataManipulators - DataTransactionResults - no FLARD
|
Squashed and merged in 4dda74c |
ghost
closed this
ghost
deleted the
Inscrutable
removed
the
needs review
The first section of the data docs is aimed at people using it for the first time, so explanations may seem overly verbose. It is not my intent to explore every detail and every possiblitity of the Data API but to give an overview and an introduction which enables the user to utilise features relying on the Data API (Items, Blocks, Entities, ...).
This PR is open to feedback regarding the content and code examples; the wording may be subject to change, though suggestions are also welcome.
Last but not least, feel free to list any topics not yet included which in your opinion seem important to have for beginner's docs.
DataManipulatorusage and use casesDataTransactionResult