Improve JavaDocs #92

lucko · 2018-04-12T18:21:39Z

I don't know if any of these changes are wanted (or welcome) or whatever - but I thought I'd PR them anyway. The only thing changed is formatting - there are no behavioural differences.

I've only just noticed that this repo is now under the SpongePowered umbrella. Does that mean it's now being actively maintained by Sponge - or did zml just want to hand over the responsibility?

If "improvement" PRs (as opposed to bug fixes) aren't going to be considered, then I'll stop submitting them & just maintain my own fork :) It would be nice to know the status - I know this probably isn't a priority for the Sponge team.

Introduce consistent formatting in Maven poms

The current poms have inconsistent formatting and indentation in some places. I rearranged & fixed indentation where it was appropriate to do so - without any change in build behaviour.

Use the correct "slashstar" style when generating license headers

The current "javadoc" style is reserved for JavaDocs - and is not meant to be used for license headers.

IntelliJ gives this suggestion/warning

👎

/**
 * Configurate
 * Copyright (C) zml and Configurate contributors
 *
 * and so on...
 */

👍

/*
 * Configurate
 * Copyright (C) zml and Configurate contributors
 *
 * and so on...
 */

JavaDoc (and other misc) improvements

These are all still WIP.

I feel like better documentation would go a long way in making configurate easier to use and understand.

The only breaking change is...

The method signature of TransformAction has been changed from

Object[] visitPath(SingleConfigurationTransformation.NodePath inputPath, ConfigurationNode valueAtPath)

to

Object[] visitPath(NodePath inputPath, ConfigurationNode valueAtPath)

SingleConfigurationTransformation is a package private class - it was previously impossible to implement the interface as a result.

The presently used "javadoc" style is reserved for JavaDocs - and is not meant to be used for license headers.

parlough · 2018-04-12T19:20:00Z

We're actively maintaining the library, I just don't think anyone has it high on their priority list at the moment. So don't worry this and other improvements are still extremely welcome, and we'll try to get to them sooner rather than later.

So thanks and keep it coming :)

lucko · 2018-04-17T18:51:32Z

Ok - good to hear :)

I think this PR is ready now - would welcome any comments or further suggestions.

kashike · 2018-04-17T20:50:45Z

pom.xml

+            <groupId>org.checkerframework</groupId>
+            <artifactId>checker-qual</artifactId>
+            <version>2.4.0</version>
+            <optional>true</optional>


I'd remove this - leave exclusions to consumers of this library.
google/guava#2721

Would <scope>provided</scope> work?

Unlike the other dependencies, checker-qual isn't needed at runtime.

For dependencies like this it makes sense for consumers of the library to include it themselves if needed imo.

Sure, you can try <scope>provided</scope>.

Provided scope works - but means checker-qual has to be specified in each of the module poms.

It really seems like setting optional to true is the best solution here?

Indicates the dependency is optional for use of this library. While the version of the dependency will be taken into account for dependency calculation if the library is used elsewhere, it will not be passed on transitively

The dependency is optional for the use of configurate, and doesn't need to be passed on transitively.

kashike · 2018-04-17T20:51:35Z

configurate-gson/src/test/java/ninja/leaping/configurate/gson/GsonConfigurationLoaderTest.java

 import ninja.leaping.configurate.ConfigurationNode;
 import ninja.leaping.configurate.SimpleConfigurationNode;
 import ninja.leaping.configurate.loader.AtomicFiles;
 import ninja.leaping.configurate.loader.ConfigurationLoader;
 import ninja.leaping.configurate.util.MapFactories;
-import org.junit.Ignore;


These should stay where they were.

kashike · 2018-04-17T20:51:52Z

configurate-gson/src/main/java/ninja/leaping/configurate/gson/GsonConfigurationLoader.java

@@ -22,6 +22,9 @@
 import com.google.gson.stream.JsonReader;
 import com.google.gson.stream.JsonToken;
 import com.google.gson.stream.JsonWriter;
+


spacing is wrong - should be all together

Unless I'm missing something, the rest of the project seems to format things this way already?

Nope nevermind, my bad. Will fix

Ok should be sorted now - I've changed my codestyle config and organised everything using the existing style

lucko · 2018-04-27T16:32:17Z

I've published a forked version of configurate containing these changes - so this can now all be previewed here:

https://javadoc.io/doc/me.lucko.configurate/configurate-core/3.4

There was quite a bit of reshuffling required to merge the current PRs together, since this one in particular has quite a large diff which spans the whole project. Those merge commits can all be found here, including a number of other changes to merge the other PRs in with the same style of javadoc improvements.

lucko/configurate@3.3...3.4 & https://github.com/lucko/configurate/releases/tag/3.4

Hopefully they can be of some use when there's activity again here.

kashike · 2018-04-27T20:40:24Z

@Meronat look good to you?

parlough · 2018-04-27T22:58:08Z

@kashike Will review this and the other PRs when I return home tonight.

lucko added 2 commits April 12, 2018 17:23

Introduce consistent formatting in Maven poms

2912c8f

Use the correct "slashstar" style when generating license headers

337d516

The presently used "javadoc" style is reserved for JavaDocs - and is not meant to be used for license headers.

lucko force-pushed the javadoc branch 4 times, most recently from a57c2b8 to afe14ed Compare April 17, 2018 18:50

lucko changed the title ~~[WIP] Improve JavaDocs~~ Improve JavaDocs Apr 17, 2018

parlough requested review from parlough and kashike April 17, 2018 18:52

lucko force-pushed the javadoc branch from afe14ed to 253708e Compare April 17, 2018 18:54

kashike suggested changes Apr 17, 2018

View reviewed changes

lucko force-pushed the javadoc branch from 253708e to 5d4e894 Compare April 17, 2018 21:12

JavaDoc improvements

8d3cc2e

lucko force-pushed the javadoc branch from 5d4e894 to 8d3cc2e Compare April 17, 2018 21:16

kashike mentioned this pull request Apr 27, 2018

Implement XML configuration loader #90

Merged

parlough approved these changes Apr 28, 2018

View reviewed changes

kashike approved these changes Apr 28, 2018

View reviewed changes

kashike self-assigned this Apr 28, 2018

kashike merged commit 676e8ba into SpongePowered:master Apr 28, 2018

lucko mentioned this pull request Jun 26, 2018

Revert compatibility break with NodePath and ConfigurationTransformation #105

Merged

lucko deleted the javadoc branch June 26, 2018 09:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve JavaDocs #92

Improve JavaDocs #92

lucko commented Apr 12, 2018 •

edited

Loading

parlough commented Apr 12, 2018

lucko commented Apr 17, 2018

kashike Apr 17, 2018

lucko Apr 17, 2018 •

edited

Loading

kashike Apr 17, 2018

lucko Apr 18, 2018

kashike Apr 17, 2018

kashike Apr 17, 2018

lucko Apr 17, 2018

lucko Apr 17, 2018

lucko Apr 17, 2018

lucko commented Apr 27, 2018

kashike commented Apr 27, 2018

parlough commented Apr 27, 2018

Improve JavaDocs #92

Improve JavaDocs #92

Conversation

lucko commented Apr 12, 2018 • edited Loading

Introduce consistent formatting in Maven poms

Use the correct "slashstar" style when generating license headers

JavaDoc (and other misc) improvements

The only breaking change is...

parlough commented Apr 12, 2018

lucko commented Apr 17, 2018

Choose a reason for hiding this comment

lucko Apr 17, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lucko commented Apr 27, 2018

kashike commented Apr 27, 2018

parlough commented Apr 27, 2018

lucko commented Apr 12, 2018 •

edited

Loading

lucko Apr 17, 2018 •

edited

Loading