Sponge Docs Pop Quiz #8

Saddle up and send out the search parties, for the

Sponge Docs Pop Quiz #8

is somewhere wandering in the woods near you.
Join us and throw your opinions onto the pile as we gather a trio of the features of our microcosm and put them under the microscope, in search of “adventure, excitement, and really wild things”.

  1. Is SpongeDocs getting ahead of the JavaDocs?
    JavaDocs are essential to the proper understanding and use of the SpongeAPI.
    They should get Priority over SpongeDocs, and we don’t wan’t to overtake them!

  2. Would a Table of Sponge equivalents to Bukkit Classes be helpful?
    This may not belong on SpongeDocs (it could get very busy quickly), but there have been many enquiries about some basic Bukkit classes and their parallel in SpongeAPI. If there is already a good resource for this, please lead us to it.

  3. Should we abbreviate the import statements in Docs code examples?
    This has been debated internally; should it be added to the SpongeDocs style guide? How much can we expect the average reader to take for granted?

A tip of the hat to you for reading, and remember you can still catch up on last week’s Quiz #7 if you’re keen for more. Stay hydrated, stay safe, and beware of the FLARD.

2 Likes
  1. No.
  2. Maybe. I’ve written a few up from time to time for various things, but it’s just soo many classes and corner cases where it doesn’t match up cleanly
  3. I believe import statements should be fully qualified so that in the event the location of the class changes, people know to look at the docs for the changes.
3 Likes
  1. I’m not sure. I don’t look at SpongeDocs enough to know.
  2. Yes. I’m planning to port a plugin for a private server to Sponge, and this would be helpful so I know when Sponge alternatives exist.
  3. Personally, I don’t use this because if I ever do a copy/paste, Eclipse automatically finds the classes for me. However, maybe there could be a collapsible import section at the top of each code example? This way, it is available for those who need it, but doesn’t take up extra space if you don’t.
1 Like
  1. I think the docs are essential to understand the API, not the javadocs. Javadocs provide in-depth information about every single part of the API, but not a good learning resource. It is so hard to identify the important classes and members in a javadoc.
  2. In general, this is a good idea. But as gabizou said, many things are handled differently in the Sponge API. You can not simply replace a few import statements to port a Bukkit plugin to Sponge. What I can imagine is a table with ~50 common code snippets (sending colored message to player, storing configuration data, simple world generator, …) translated from Bukkit to Sponge, with a short explanation of the differences.
  3. No. The import statements are not disrupting readability. Some things could be streamlined with static imports (command api) or inline imports. But I don’t know if that is good coding practice.
2 Likes
  1. I think that the JavaDocs serve another purpose as SpongeDocs. The former gets you a deep insight into the API, the latter is a quick reference, a summary of guides and allows newbies to get a good overview.

  2. I think several guides with use cases might fit better than a comparison table. To me it’s more helpful to show plugins devs how something is done in Sponge and not to compare the way of another API (here: Bukkit) and ours.

  3. I’d leave them where they are or make it depend on the case/example.

2 Likes