Add documentation for Util class #5
Conversation
sciwhiz12
added
the
documentation
| * This is used to initialize collections in static fields with their contents (without using builders such as | ||
| * @ref ImmutableMap.Builder). |
There was a problem hiding this comment.
Not a good example to include for this method. If an immutable map was to be created, it would still need to go through builder to input the corresponding elements. Otherwise the method itself would need to be wrapped within the map's copyOf method or called with Buiilder#build. This is why the above method exists with the supplier to allow access to the builder and constructing within one method without an external invocation.
| */ | ||
|
|
||
| /** | ||
| * @fn public static <T> Optional<T> Util::acceptOrElse(Optional<T> opt, Consumer<T> consumer, Runnable orElse) |
There was a problem hiding this comment.
For those more familiar with Java 9+, I would suggest mentioning its equivalent Optional#ifPresentOrElse.
| /** | ||
| * @fn public static void Util::backupThenUpdate(File current, File latest, File oldBackup) | ||
| * | ||
| * Backups the first file to the third file, then updates the first file from the second file. |
There was a problem hiding this comment.
These should use the parameter names instead of the parameter order.
| * Returns a @ref DataResult with the integers from the stream, depending on the amount of remaining elements. | ||
| * | ||
| * This method returns a @ref DataResult with an array of integers from the stream if it contains at least @p size integers; | ||
| * else it will return a failed @ref DataResult, which may contain the remaining integers in the stream, if any. |
There was a problem hiding this comment.
If the length of the array is not larger than or equal to the specified size, no partial result will be given (meaning the array will not be passed in), only the error message.
| /** | ||
| * @fn public static void Util::func_240984_a_(Path p_240984_0_, Path p_240984_1_, Path p_240984_2_) | ||
| * | ||
| * Copies the source path from the parent path to the destination path. |
There was a problem hiding this comment.
p_240984_0_ can be considered to be the root directory in this case. p_240984_2_ is the subdirectory within p_240984_0_ to which the relative path is constructed. Then, the resulting relative path is applied to p_240984_1_, where the files from p_240984_2_ are copied towards. It would be more appropriate to call them the original root, new root, and resolved path.
As an example, if we had the following arguments a/b, e/f, and a/b/c/d, path would grab the following relative c/d/ and apply it to e/f resulting in e/f/c/d. The file is then copied from a/b/c/d to e/f/c/d.
| * | ||
| * The default supplier returns the value of @ref System#nanoTime(). | ||
| * The value is not related to system or wall-clock time. It only measures the time in nanoseconds since some arbitrary | ||
| * "origin" time. All invocations of this method within a JVM instance will return from the same time-source and origin time. |
There was a problem hiding this comment.
Add a "for getting the time since a know point use millisecondsSinceEpoch()"
| */ | ||
|
|
||
| /** | ||
| * @fn Util::getValueName(Property<T> property, Object value) |
There was a problem hiding this comment.
This ones seams to be missing the return type in the signature
| * | ||
| * Creates a translation key for the given nullable @ref ResourceLocation based on the given type. | ||
| * | ||
| * If the @p id parameter is @c null, then the returned translation key will be <tt>type + ".unregistered_sadface"</tt>. |
There was a problem hiding this comment.
I'm guessing it works with any type not just the ones that actually exist. But let's spell it out I think.
| * Returns the current value of the JVM's time source in milliseconds. | ||
| * This is equivalent to calling <tt>Util.@ref nanoTime() / 1000000L</tt> | ||
| * | ||
| * @return The current value of the JVM time source in milliseconds. |
There was a problem hiding this comment.
See Util::nanoTimeSupplier
And smae for the one below
| /** | ||
| * @fn public static Type<?> Util::attemptDataFix(TypeReference type, String choiceName) | ||
| * | ||
| * Attempts to create a data fixer for the given @ref TypeReference. |
There was a problem hiding this comment.
I'm guessign this would link to the data fixer docs if that would exist....
| */ | ||
|
|
||
| /** | ||
| * @fn public static <K> Strategy<K> Util::identityHashStrategy() |
There was a problem hiding this comment.
This one seams to have a wrong signature.
| */ | ||
|
|
||
| /** | ||
| * @fn Util::gather(List<? extends CompletableFuture<? extends V>> futuresIn) |
| * Returns the given @ref Runnable with the given supplied name. | ||
| * | ||
| * The implementation of this simply returns the passed in runnable directly. | ||
| * However, this method if edited by developers can be changed to wrap the runnable in another runnable before returning, |
There was a problem hiding this comment.
Should this method be edited... Feels wired to suggest it, and sound like core modding.....
| */ | ||
|
|
||
| /** | ||
| * @fn public static <T extends Throwable> T Util::pauseDevMode(T throwableIn) |
There was a problem hiding this comment.
Maybe we could add soemthing for the methods that are Mojang used and we don't really know what they are for.....
| * Returns a random object from the given array, based on the given @ref Random. | ||
| * | ||
| * The randomness of the selection shall conform to the characteristics of the given @ref Random, based on the | ||
| * behavior of @ref Random#nextInt(int). |
There was a problem hiding this comment.
Does this mean it uses the Random#nextInt(int) ? Or somehting more complicated?
Adds documentation for the
net.minecraft.util.Utilclass.Notes:
\for the Doxygen commands, for two reasons:@character is more easily distinguishable from the surrounding text than\.@fnstructural comment. Doxygen does fine without the generics, however the detailed section for that method will have the generics missing. ToTo mitigate this, I also pasted the complete method signature of the methods into their description. (Any advice on how to fix the problem better would be appreciated.)
Util.attemptDataFix. For the sake ofpreserving my sanityminimizing the total time that I invest in this singular class, I will leave documenting it to future contributors.