isXander / isXander/YetAnotherConfigLib

Docs: Open-sourcing the wiki / documenting source-only behaviors

Open
#360 0 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Java
Stars
155
Forks
68
PR merge metrics
No merged PRs in 30d

Description

Love YACL, but the wiki has fallen pretty far behind modern releases (v3, ConfigClassHandler, new controllers, etc.). Most non-trivial implementations currently require digging through src/ or other mods' codebases.
This was already mentioned in #345, but I wanted to give a few more pointeres where the wiki lacks behind.

Is the documentation source hosted publicly anywhere? If the GitBook source can be mirrored to a docs/ directory (or synced with GitHub), I’d gladly submit PRs to help flesh these out.

If not, a quick reference covering the biggest blind spots would save everyone a ton of reverse-engineering:

  • GUI Autogen: How @AutoGen and its related annotations work to generate UI screens directly from config classes. This is the way to write modern yacl but it's entirely undocumented!
  • ConfigClassHandler & @SerialEntry Semantics: What happens on missing, new, or removed fields, parse error fallbacks, default GSON codecs, and registering custom type serializers.
  • Bindings & Value Lifecycle: When setters actually fire (on change vs. on save), how pending vs. committed state works, and reset button logic.
  • Option Dependencies & Dynamic Availability: The undocumented pattern for making options conditionally available/greyed-out based on other toggles.
  • OptionFlags: Exactly what triggers when built-in flags (GAME_RESTART, ASSET_RELOAD, etc.) are attached, and how custom flags work.
  • Input Validation: How to hook up validators, reject malformed inputs, and what error feedback displays in the UI.
  • State Managers: How StateManager operates and integrates with option state.
  • Custom Controllers: An actual implementation guide for Controller and ControllerWidget to replace the empty wiki heading.
  • Translation Conventions: Automatic lookup keys for option labels, descriptions, enum cycling, and tooltips.
  • Version Matrix: Updating the supported Minecraft/YACL version mappings past 1.21.2.

I know in the age of AI one can just let their agent dig throug the codebase for five minutes to find the answers, but this is such a waste of resources compared to having a clear markdown based wiki easily accessible.

If there's a repo open for doc contributions, please let me know :)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by checking whether the GitBook source is publicly hosted and review the existing wiki alongside the source in src/. Map the documented gaps around GUI Autogen, ConfigClassHandler, bindings, dependencies, flags, validation, state managers, custom controllers, translations, and version mappings. Done means a publicly accessible documentation source or focused reference covering the identified behaviors.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.