Improve Javadocs: Project and Package descriptions

[boformer]

To make the javadocs more self-explaining, there should be a project description that is displayed on the index page (overview.html).

The description can also include a link to the SpongeDocs.

Also, there should be a description for every package (package-info.java).

[phase]

Isn't that what the SpongeDocs are for?

[Xemiru]

@phase not necessarily, the docs are for explaining things in a way that's more user-friendly, for all the n00bies, whether its Sponge or development in general (to some extent). this is just for extra clarification of the project, and parts of it. not so important, but it doesn't hurt to add it either.

[gabizou]

Usually the packages are pretty self evident in regards to what they do. What more description would a package gain?

[boformer]

@gabizou the Bukkit docs are a good example: http://www.javaminecraft.com/bukkitapi/overview-summary.html

The package description can contain a link of a related class (e.g. player events --> Player) and describe the contents of a package.

I don't think that all package names are self-explaining.

[ST-DDT]

This overview is really nice. I would love to see something similiar for sponge as well.

Especially the following packages could benefit from this:

• util.gen
• world.gen
• util.reflect
• text.translation.locale
• service.sql
• world.storage
• status
• persistance.data
• block.meta
• block.data

For some you can guess them but others may be confusing due to their similar names.

[caojohnny]

I'd like to see this implemented

[ST-DDT]

Anyone willing to do this? Or is this something the team would do?

If not I would offer my help on this.

[boformer]

This is an open source project. Just go ahead ;)

[ST-DDT]

The current progress for package javadocs: 100% (Compare)

If you have any wishes or suggestions please tell me so i can add them soon.

Package	Description
...api	Core classes in the API with general purpose.
...api.attribute	Classes to manipulate Attributes such as MAX_HEALTH and MOVEMENT_SPEED.
...api.block	Classes used to manipulate block states of block volumes such as worlds.
...api.block.tileentity	Classes that represents special data holder blocks.
...api.block.tileentity.carrier	Classes that represents special data holder blocks with inventories.
...api.data	Classes used to store and manipulate data on a wide variety of data holders, replaces the insecure NBT access.
...api.data.manipulator	Data classes that can be used to add, alter, copy and delete data from DataHolders.
...api.data.manipulator.block	Data classes that can be used to add, alter, copy and delete data from blocks.
...api.data.manipulator.catalog	Utility classes listing all data classes applicable to a specific part of the API.
...api.data.manipulator.entity	Data classes that can be used to add, alter, copy and delete data from entities.
...api.data.manipulator.item	Data classes that can be used to add, alter, copy and delete data from item stacks.
...api.data.manipulator.tileentity	Data classes that can be used to add, alter, copy and delete data from tile entities.
...api.data.property	Classes that represent immutable data properties.
...api.data.type	Enum like classes used in DataManipulators.
...api.effect	Classes representing visual or audible effects for viewers.
...api.effect.particle	Classes representing visual particle effects for viewers.
...api.effect.sound	Classes representing sound effects for viewers.
...api.entity	Classes for non-voxel objects that can exist in a world, including all players, monsters, projectiles, etc.
...api.entity.explosive	Classes for entities that can explode such as TNT.
...api.entity.hanging	Classes for hanging entities such as decorative item frames.
...api.entity.living	Classes for living entities such as players and monsters.
...api.entity.living.animal	Classes for living Animals such as cows and sheeps.
...api.entity.living.complex	Classes for complex entities such as the ender dragon.
...api.entity.living.golem	Classes for golems.
...api.entity.living.monster	Classes for Monsters such as creepers and skeletons.
...api.entity.player	Classes for players.
...api.entity.player.gamemode	Should be moved
...api.entity.player.tab	Classes for player's tab lists.
...api.entity.projectile	Classes for projectiles.
...api.entity.projectile.explosive	Classes for explosive projectiles.
...api.entity.projectile.explosive.fireball	Classes for fireball projectiles.
...api.entity.projectile.source	Classes for projectile sources.
...api.entity.vehicle	Classes for vehicles such as boats and Minecarts.
...api.entity.vehicle.minecart	Classes for minecart.
...api.entity.weather	Classes for weather related entities.
...api.event	Classes dedicated to handling triggered code executions.
...api.event.attribute	Events related to attributes.
...api.event.ban	Events related to bans.
...api.event.block	Events related to blocks.
...api.event.block.tileentity	Events related to tile entities.
...api.event.cause	Classes for event causes and reasoning.
...api.event.cause.reason	Classes for event reasoning.
...api.event.entity	Events related to entities.
...api.event.entity.living	Events related to living entities.
...api.event.entity.living.human	Events related to humans including NPCs and players.
...api.event.entity.living.human.fishing	Events related to fishing humans.
...api.event.entity.living.player	Should be moved
...api.event.entity.minecart	Events related to minecarts.
...api.event.entity.player	Events related to Players excluding NPCs.
...api.event.entity.player.fishing	Events related to fishing players.
...api.event.inventory	Events related to inventories.
...api.event.message	Events related to messages such as commands and chat.
...api.event.network	Events related to network communication.
...api.event.rcon	Events related to the remote console access.
...api.event.server	Events related to the Server.
...api.event.server.query	Events related to the Server queries.
...api.event.state	Events related to the state of the game.
...api.event.statistic	Events related to in game Statistics.
...api.event.weather	Events related to weather effects.
...api.event.world	Events related to the world.
...api.extra.skylands	Classes related to the skyland world generation.
...api.item	Classes related to item stacks and inventories.
...api.item.inventory	Classes related to inventories.
...api.item.inventory.crafting	Classes related to crafting inventories.
...api.item.inventory.custom	Classes related to custom inventories.
...api.item.inventory.entity	Classes related to inventories for entities.
...api.item.inventory.equipment	Classes related to equipment inventories.
...api.item.inventory.property	Property classes related to inventories.
...api.item.inventory.slot	Classes for different inventory slot types.
...api.item.inventory.transaction	Transaction classes related to inventories.
...api.item.inventory.type	Classes for different inventory layouts.
...api.item.merchant	Classes related to merchants and item trading.
...api.item.recipe	Classes related to (crafting) recipes.
...api.network	Classes related to network communication.
...api.plugin	Classes related to plugins and plugin management.
...api.potion	Classes related to potion effects.
...api.resourcepack	Classes related to resource packs.
...api.scoreboard	Classes related to scorebards.
...api.scoreboard.critieria	Classes related to scoreboards defining the update behavior.
...api.scoreboard.displayslot	Classes related to positioning scoreboards.
...api.scoreboard.objective	Classes related to tracking the actual score value for the entiries in scoreboards.
...api.scoreboard.objective.displaymode	Classes defining the look of the values displayed by scoreboards.
...api.service	Classes related to service management as well as service definitions.
...api.service.ban	Service classes related to ban management.
...api.service.command	Service classes related to command management.
...api.service.config	Service classes related to config management.
...api.service.event	Service classes related to event management.
...api.service.pagination	Service classes related to pagination handling.
...api.service.permission	Service classes related to permission management.
...api.service.permission.context	Classes used to separate different permission contexts.
...api.service.permission.option	Permission holder classes more data than just permissions.
...api.service.persistence	Classes related to managing and persisting data objects.
...api.service.profile	Classes related to fetching game profiles.
...api.service.rcon	Service classes used to obtain details about the remote console.
...api.service.scheduler	Service classes related to timed code executions.
...api.service.sql	Service classes related to sql connection management.
...api.service.user	Classes related to fetching user profiles.
...api.statistic	Classes related to ingame statistics.
...api.statistic.achievement	Classes related to achievements.
...api.status	Classes related to server status publishing.
...api.text	Classes related to messaging and text displaying and formating.
...api.text.action	Classes related to actions bound to text parts.
...api.text.chat	Classes for controlling the type of text being send.
...api.text.format	Classes related to Text formating such as colors and style.
...api.text.selector	Classes related to selectors.
...api.text.sink	Classes related to message sinks (message target bundles).
...api.text.title	Classes related to title screens.
...api.text.translation	Text classes related to multi language support.
...api.util	Multi and single purpose classes to facilitate various programmatic concepts.
...api.util.annotation	Utility annotation classes.
...api.util.ban	Utility classes related to player and user bans.
...api.util.blockray	Block ray tracing utility classes.
...api.util.command	Utility classes related to commands.
...api.util.command.args	Utility classes related to command arguments.
...api.util.command.args.parsing	Utility classes related to command argument parsing.
...api.util.command.dispatcher	Utility classes related to command dispatching.
...api.util.command.source	Utility classes related to command sources.
...api.util.command.spec	Utility classes related to command specifications.
...api.util.event.callback	Utility classes related to event callbacks.
...api.util.event.factory	Utility classes related to event instance/class generation.
...api.util.event.factory.plugin	Utility classes related to event instance/class generation extensions.
...api.util.event.superclasses	Utility class for generated event classes.
...api.util.reflect	Classes related to java reflections.
...api.util.rotation	Utility classes related to rotations.
...api.util.weighted	Classes related to weighted randomization.
...api.world	Classes related to the world and its properties.
...api.world.biome	Classes related to the world's biomes.
...api.world.difficulty	Classes related to the worlds difficulty.
...api.world.extent	Classes related to virtually separating worlds into smaller pieces and working with them.
...api.world.gamerule	Classes related to the world's game rules.
...api.world.gen	Classes related to world generation.
...api.world.gen.populator	Classes related to the world population (blocks only).
...api.world.gen.type	Classes related to type definitions for the world generator.
...api.world.storage	Classes related to world storage access.
...api.world.weather	Classes related to the weather in a world.

[boformer]

"Classes" is maybe a bad word (though the Bukkit javadoc also uses the word). Many parts of the API are actually interfaces

Very nice work! I think this really improves the quality of the javadoc!

[caojohnny]

"Classes" describes Java-specific file best, i.e. you wouldn't say "This .java file does yadayada ydada" but "This class does yada yada yada".

[ST-DDT]

Done. Anyone wants to suggest some changes before i create a PR? ~130 package-info.java files

I know the descriptions are short but IMO this is a good starting point and will ease the work to add more or to enhance the existing.

[caojohnny]

Possibly highlight some important classes in that particular package possibly?

[ST-DDT]

I linked a lot of classes, but i could not export it to my github comment. You can see the links when following the "Compare" link above the list. For sub-packages this is really hard as there is less important stuff in there.

[caojohnny]

Ah I can understand that.

[ST-DDT]

Java only shows the first sentence in the listing so i focussed on writing that part.

I also thought about adding some examples for each paackage, but I'm lacking knowledge on some of the packages and i also don't know whether that will get appreciated.

Something like this Data API Example.

[boformer]

Very nice!

[Deamon5550]

Don't include examples.

[ST-DDT]

I created a PR for this: https://github.com/SpongePowered/SpongeAPI/pull/757

[Zidane]

Now apart of the OCD list.