Data API Docs

[ghost]

The Data API Docs have commenced to exist, but as gabizou put it so aptly, they merely scratch the tip of the Iceberg. Since the Data API is such a prominent feature of Sponge it deserves thorough explanation, which is mainly why the currently existing docs cover only a part of what I originally intended to write about. I'll continue to dive into the API and once I've understood enough, come back to add another page to the docs. I can in no way give an ETA or anything, so I present my To Do list here, with unmarked items free for anyone to give a shot at.

To Do List:

• Basic stuff
  • Using Keys to retrieve and alter Data (Data Docs 2.0 #331)
  • Using keyed Values (Data Docs 2.0 #331)
  • DataManipulator usage (Data Docs 2.0 #331)
  • Getting Information from a DataTransactionResult (Data Docs 2.0 #331)
  • Persistence / Serialization Tools (DataContainer, DataBuilder) (Data Serialization Docs #363)
• advanced Applications
• Using existing DataManipulators on custom Objects
• Implementing custom DataManipulators
• Storing Custom Data on existing DataHolders
• Contributing
  • Implementing DataManipulators in Sponge (add DataManipulator contribution docs #321)
    • Determining if a DataManipulatoris testable without an Implementation and annotating accordingly
    • Contents of this comment
    • In step six, reflect the renaming of SpongeSerializationRegistry to the new class.
    • Add basic documentation for DualProcessors as these are currently not mentioned.

(existing, in the context of the above list, means 'existing in the SpongeAPI')

Resource List:

• Original Data API PR
• Value API Addtions PR
• "How to use Data API 2.0" Forums Thread

[Inscrutable]

"if a plugin wants to have a custom data manipulator, they need to register their DataManipulatorbuilder in GameInitializeServerEvent or whatever it is" - more info from gabizou

[ghost]

https://github.com/SpongePowered/SpongeAPI/pull/940/files Abstract Data in API.

[Tzky]

We need to add a @ImplementationRequiredForTest annotation to DataManipulators (the contrib Docs), as @gabizou added a parametarized ManipulatorTest. This applies to data manipulators that deal with objects that are entirely implementation dependent; i.e. anything that is a CatalogType, Text, Entity, ItemStack etc.

example:
SpongePowered/Sponge@8671c6d#diff-4b9152d5e765fd6b123a23662ec19a44R38

[gabizou]

Just to add some examples of working custom data. The demo plugin will create FakeData and assign it to a Player who executed the /fakeData command and the /validateData command will check that the data exists on the Player who executed it. It's rudimentary but it exemplifies what is minimally required for custom data that persists properly between world loads and server restarts.

https://gist.github.com/gabizou/4219d260b00fe8624fa2

[Inscrutable]

Custom Data changes here and here. "those two should basically suffice document writing" gabizou assures me...
Also, if @Saladoc is indisposed, we might need someone new to take control of this issue.

[Inscrutable]

We can also add #559 to the omnibus of Data stuff to get down with. SpongeDocs need someone who can help get this back on track. Whomsoever shall yadda yadda ...

[ST-DDT]

I might have a look at this once its gets a little bit colder...

[ST-DDT]

I didn't forget it (yet). I just pushed it further down the road. Somehow I feel like this issue is a ⛰⛰⛰.
(if anyone wants to go ahead...go ahead^^)

[Inscrutable]

This, and Inventories, are probably the two hardest subjects we have yet to tackle. It's been the downfall of one Editor in the past; what we really need is someone who is familiar with using it.