Skip to content

Conversation

@WaitingIdly
Copy link
Collaborator

significant changes:

  • now possible to provide custom annotations to methods that are only in superclasses of the target class (method name if unique, otherwise requires descriptor).
  • builder admonition blocks got a spruce-up:
    • can now have a custom title and document the method directly.
    • now has section breaks between title/description/methods/registration/example.
  • builder can now handle initialization methods with parameters correctly.
  • some additional logging for this and for potentially missed classes (INamed registry missing annotation).

changes in this PR:

  • create @MethodOverride and @RecipeBuilderOverride annotations.
    • add method to @MethodDescription, @RecipeBuilderDescription, @RecipeBuilderMethodDescription, and @RecipeBuilderRegistrationMethod to support being used in these overrides.
    • @MethodOverride can contain any number of @MethodDescription and @RecipeBuilderDescription annotations, but they must define method.
    • @RecipeBuilderOverride can contain any number of @RecipeBuilderMethodDescription and @RecipeBuilderRegistrationMethod annotations, but they must define method. Further, it can contain any number of @Property annotations.
    • deprecated RecipeBuilderDescription#requirement in favor of using RecipeBuilderOverride#requirement
    • the @RecipeBuilderDescription annotation also gained the ability to specify the return value of the class via RecipeBuilderDescription#clazz.
    • updated javadocs to support using these new annotations.
    • applied these new annotations in a large number of places - due to this, 63 stub methods were removed (method existed purely for annotation).
  • improve documentation for recipe builders.
    • change the default name from the method to create the recipe builder (ie mods.actuallyadditions.crusher.recipeBuilder()) to Recipe Builder, with the ability to be customized via RecipeBuilderDescription#title or via a default lang key (groovyscript.wiki.{modId}.{name}.{methodName}.title).
    • add a entry describing the method to create the recipe builder - this is where mods.actuallyadditions.crusher.recipeBuilder() goes. Add a default description of Create the Recipe Builder, but as before this can be customized via RecipeBuilderDescription#description or via a default lang key (groovyscript.wiki.{modId}.{name}.{methodName}.description).
    • applied this in a large number of cases - particularly, those where the builder was named something other than recipeBuilder.
    • add the ability to document builder methods with parameters.
    • add logging for incorrect examples - complex builder methods require starting with (, all others require starting with ..
    • updated javadocs to support using these new annotations.
  • adjust and extract a number of methods to facilitate the above changes
    • create DescriptorHelper to handle string->method targeting and a handful of previously scattered methods.
    • create ComparisonHelper to handle sorting of various things - primarily annotations.
    • create LangHelper to handle translations and punctuation.
    • create GenerationFlags to handle reading system properties.
  • fix some small incorrect things:
    • fix a typo with roots predicate description.
    • fix the alchemistry dissolver not overriding the output method to point to probabilityGroup, and incorrectly marking output as being used.
    • fix the astral sorcery fountain using duplicate or unneeded lang keys.
    • fix compact machines miniaturization not marking the method duration as pointing to ticks.
    • fix a few typos in comments in files already changed.
  • ensure the link generator domain and path end in /, solving an annoying common issue of "author forgot it".
  • fix not using variable IFormat and instead referencing static constant in some places.
  • suppress StringBufferMayBeStringBuilder due to it being an invalid warning for the java version we use.
  • add logging for skipped classes that are not documented due to missing the @RegistryDescription annotation.
  • make the defaultValueConverter not incorrect regarding primitive wrapper classes. Further, change longs to use 0L.
  • add section breaks (---) between segments of the recipe builder admonition.

@WaitingIdly WaitingIdly added documentation Improvements or additions to documentation enhancement New feature or request labels Apr 17, 2025
Copy link
Member

@brachy84 brachy84 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@brachy84 brachy84 merged commit 9deea57 into CleanroomMC:master May 5, 2025
@WaitingIdly WaitingIdly deleted the document-method-via-descriptor branch May 6, 2025 06:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants