Ongoing Minor Issue List (OCD List) SpongeDocs Edition

[Tzky]

I'd like to start an OCD post on the Docs repo, this way we don't push minor fixes but instead collect them and push them in bunches.

@SupaHam reported these two in '#sponge:

• in /plugin/debugging phrasing in L91:
  • mention of Sponge(Vanilla) and missing SpongeForge
  • "the sentences don't make any sense in this particular order"
• in /plugin/event/causes: Optionml<Entity> in L45

according to PR#447:

• in plugin/optional/usage.rst (L166): if (optinalString.isPresent())

I'll quote @phroa here:

• the link to GenericArguments' source code on the argument parsing section is busted, should be https://github.com/SpongePowered/SpongeAPI/blob/master/src/main/java/org/spongepowered/api/command/args/GenericArguments.java

@Dannyps reported:

• in server/getting-started/configuration/index : Saving a world config may be desired *after making modifications to the file*. is confusing. It should read: Saving a world config to the file may be desired after making modifications.

[Deamon5550]

• in /plugin/wgen/modifiers the example for registering the world generator modifer needs to be updated to Sponge.getRegistry().register(WorldGeneratorModifier.class, new MyModifier());

[12awsomeman34]

• The page about/introduction mentions that the project leaders are blood, sk89q, and Zidane. This should be updated in accordance with about/staff.
• In the second example under "Altering Block States" on the block docs, coarseData should be renamed to podzolData, or more preferably dirtData (with the first dirtData being renamed to optionalData or something), as the DirtType is PODZOL, not COARSE_DIRT. Same with courseState (which is incorrectly spelled anyway).

[RedNesto]

• There is "how to" written twice in the latest Docs update: a33b982#diff-1b21b02d7e6287095c0a769eab09ebc1R124

[Tzky]

• the .. note:: block on the downloads page needs rephrasing/clarification, as it stands it doesn't make any sense.

[12awsomeman34]

• In registering the command on the CommandCallable page, the example should be updated:
  new MyBroadcastCommand(server) -> new MyBroadcastCommand()

[ghost]

At plugin/injection, there is some text that reads It’s entirely possible to receive the Game object from within most events [...] which should probably read It’s entirely possible to receive the Game object from Sponge.getGame().

Also in that file, towards the bottom, there is some text that reads [...], where @ConfigDir refers to a directory. I think the where should be a while.

[Inscrutable]

I think it was meant to read whereas instead of where. I can't speak for the other issue though.

[stephan-gh]

• posting.rst under Categorizing Your Posts: it's category -> its category. Reported on Crowdin by tomudding

[Inscrutable]

A couple of issues raised by translators:

• at /contributing/implementation/datamanipulator.rst:46 ..."you want to have two constructors:" should be "you need to have two constructors:". (want to is poor wording does not translate well)
• at /server/getting-started/configuration/server-properties.rst:384: "white list" should be "whitelist" for consistency.

[randombyte-developer]

The permissions docs suggest using the plugin id as the 'root permisison node'. The example is myPlugin.
The plugin id docs say that plugin ids must be lowercase. And the example from the permission myPlugin isn't lowercase.

[vectrixdevelops]

• https://docs.spongepowered.org/stable/en/plugin/injection.html#temporary-list-of-injected-types ConfigDir example should point to the ./configs/ directory instead of ./mods/.

[Inscrutable]

A new one found by tomudding:

• "sections" should not be a plural in the first line of https://docs.spongepowered.org/stable/en/contributing/index.html

[Inscrutable]

• https://docs.spongepowered.org/stable/en/about/faq.html#i-m-a-bukkit-plugin-developer-why-can-t-sponge-use-bukkit-s-api says "demise in September". This should have the year (2014). c/o - kashike

[Faegy]

• https://docs.spongepowered.org/stable/en/plugin/event/causes.html#event-causes misses "be" in "This contextual information can then used to modify the behavior of your event listener".
• https://docs.spongepowered.org/stable/en/plugin/event/causes.html#retrieving-objects-from-a-cause is missing the link for "for a more complete listing please see the javadocs link.".

[stephan-gh]

• "Is are" #604

[randombyte-developer]

https://docs.spongepowered.org/stable/en/plugin/scheduler.html#task-properties

For the task name:

... could look like “FooPlugin-A-12”. No two active tasks ...

The plugin id should be foo-plugin.

[Inscrutable]

OK, Everything here has been fixed up to this point in PR #616 - let me know if anything's awry.

[ryantheleach]

https://docs.spongepowered.org/stable/en/server/spongineer/commands.html Should mention the /minecraft:xyz fallbacks in an info box.

[MinusKube]

The text Examples of block properties in plugin/blocks/concepts.rst is not translatable.
I guess it's due to the topic.

https://github.com/SpongePowered/SpongeDocs/blame/stable/source/plugin/blocks/concepts.rst#L13

[Inscrutable]

Regarding the plugin/blocks/concepts page issue: As we rarely used topic anywhere in the docs, we can reformat that bit and see what happens. It should be editable, just like the contents of a note or a tip, but we have noticed some eccentricities in the translatable parts on Crowdin recently.

[Dannyps]

• https://github.com/SpongePowered/SpongeDocs/blame/stable/source/ore/publish.rst#L96
  If you're using build manager should be If you're using **a** build manager. I think.

[Inscrutable]

• On the server/getting-started page, SpongeForge needs at least Java 8 build 20, not 40.

[ST-DDT]

• https://github.com/SpongePowered/SpongeDocs/blame/stable/source/plugin/economy/practices.rst#L64

Is:

if (result.getResult() == ResultType.SUCCESS)) {

Should be:

if (result.getResult() == ResultType.SUCCESS) {

(Remove duplicate bracket)

As reported by #668 .

[ST-DDT]

• https://github.com/SpongePowered/SpongeDocs/blame/stable/source/ore/publish.rst#L156

is:

If you hover choose to add it to another page the page will only show when the parent page is expanded.

Mentioned by @Dannyps on IRC:

Isn't the word hover an intruder, in that line?

[TheNullablePrototype]

An error in the documentation or something I do not understand?
http://joxi.ru/MAjlOW5u4My50m
https://docs.spongepowered.org/stable/ru/plugin/offline-userplayer-data.html#code-example

[ST-DDT]

@ImagePrototype Yes thats an error in the documentation:

Should probably be:

if (onlinePlayer.isPresent()) {
	return onlinePlayer.map(v -> v);
}

Ref: https://github.com/SpongePowered/SpongeDocs/blame/stable/source/plugin/offline-userplayer-data.rst#L44

But this piece of code looks too confusing anyway. We should probably ask the API team for the recommended way to do it.

EDIT: According to killjoy checking the online players first is unnecessary overhead.

[Inscrutable]

That one probably justifies a separate issue, if only so we can add a reviewer or two. It certainly seems to be larger than the usual trivial issues we put here.

[tomudding]

A few Terms of Service related issues:

• https://github.com/SpongePowered/SpongeDocs/blame/stable/source/about/tos.rst#L105
  It should be (3.4) Ore because Ore should be outside the parentheses, like all other platforms mentioned.

• https://github.com/SpongePowered/SpongeDocs/blame/stable/source/about/tos.rst#L33
  Missing a , between “Our” “SpongePowered”.

[Grauldon]

I have 7 more commits ready for another PR. I am going through this list and checking for more changes I can make. I hope to have a PR ready in the next day or two.

[Grauldon]

---

I have commits ready for the following issues:

ST-DDT's comment about sentence duplication on Oct 14, 2017

MinusKube's comment about translating section title on Jan 30, 2018 and Inscrutable's response on Jan 31, 2018

Dannyps' comment about a sentence missing "a" on Feb 12, 2018

ST-DDT's comment about removing an extra ")" in example on Feb 26, 2018

ST-DDT's comment about an extra word in sentence on Mar 1, 2018

Inscrutable's comment about the minimum Java 8 build on Feb 14, 2018

Dannyps' comment about the query parameters table on Aug 25, 2017

---

I can do the work for the following issues; I just need some guidance and/or decisions from someone more familiar with the documentation/code:

ST-DDT's comment about section title on Oct 14, 2017

Phit's comment about the config files need some cleanup on Dec 10, 2017

ryantheleach's comment about mentioning the /minecraft:xyz fallbacks on Jan 8, 2018

ST-DDT's comment about Code Style/formatting and correcting a sentence on Nov 19, 2017

---

Once these issues are resolved, the only remaining issue after PR #616 is the SpongeAPI vs Sponge API comments starting with tomudding.

ImMorpheus' comment is complete AFAICT, but I have not checked the full list.

[ST-DDT]

ST-DDT's comment about section title on Oct 14, 2017

Go for PotionEffects

Phit's comment about the config files need some cleanup on Dec 10, 2017

AFAICT this refers to the config files itself and not the documentation, so there is nothing for us to do here.

ryantheleach's comment about mentioning the /minecraft:xyz fallbacks on Jan 8, 2018

Just write a short paragraph mentioning this and we will comment on it in your PR.

ST-DDT's comment about Code Style/formatting and correcting a sentence on Nov 19, 2017

Add linebreaks and go for Contributors.

Once these issues are resolved, the only remaining issue after PR #616 is the SpongeAPI vs Sponge API comments starting with tomudding.

IMO this can be ignored. If someone finds a wrong usage of this term he should report it here or fix it. Because otherwise we need a grammar master to identify them all. We should pay attention to that in new PRs though.

[ryantheleach]

ryantheleach's comment about mentioning the /minecraft:xyz fallbacks on Jan 8, 2018

in short, when there are conflicting commands in Sponge, that conflict with the games native commands, we also have the command's primary alias, with a prefix of the mod/game/plugin.

So if someone registers a /tp command in a plugin, that is say, incompatible with your camera mod, if you can configure your camera mod to use /minecraft:tp instead, you will get the expected behavior again.

The same goes with conflicting commands from multiple plugins. e.g. you could have /nucleus:tp and /easywarps:tp

It's a common question that appears on the forums occasionally.

[Grauldon]

I have the changes ready. I just need to sort out some issues with git / github. I am still getting git's workflow down.

[ST-DDT]

Once @Grauldon 's changes are included, I will update most code examples.
The PR for that is almost ready just waiting for SpongePowered/SpongeAPI#1839 (comment).

[ST-DDT]

AFAICT we have now solved all issues listed here, so I guess we can close this issue (and create a new one for future comments). Objections?

[phit]

we could also delete all comments that are no longer relevant, similar to other minor issue lists in the org

[Inscrutable]

I would rather close this issue and keep the comments, and just make a Fresh issue. Should we continue calling it the 'OCD' List (which does have unwanted connotations), or something a little more sanitised?

[phit]

I'd say drop the parentheses, and just call it "Ongoing Minor Issue List SpongeDocs Edition" and make a new issue

[Inscrutable]

Closing this to make way for the new-born #698