beyond-all-reason / beyond-all-reason/RecoilEngine
Improve docgen accessibility
- Dominant language
- C++
- Stars
- 679
- Forks
- 290
- Avg merge
- 3d 2h
- Merged PRs (30d)
- 40
Description
I'm aggregating on this issue a few standing issues regarding the current generated documentation:
- [ ] Consider making a "spring wiki" layout, see https://github.com/beyond-all-reason/RecoilEngine/issues/1430#issuecomment-3076591843
- [ ] Improve short signature codeblock for function templates
- [ ] Consider inlining aliases (or at least short aliases)
- [ ] Aliases are truncating, e.g. `a|b|c...` without offering a way to expand to their whole definition (blocked until https://github.com/EmmyLuaLs/emmylua-analyzer-rust/issues/623 is released)
- [ ] We need to find a straightforward way to specify/document conditional return values, especially when the function arguments don't differ (they can't be split into overloads).
- [ ] https://github.com/beyond-all-reason/RecoilEngine/issues/1204 Implement `@x_section` handler for grouping types together within a namespace
- [ ] Implement `@x_callin` handler for marking global functions as callins
- [ ] https://github.com/beyond-all-reason/RecoilEngine/issues/1959 Implement `@x_env` handler for tagging and grouping types per environment, e.g. `@x_env LuaUI LuaRulesUnsynced` (blocked by https://github.com/EmmyLuaLs/emmylua-analyzer-rust/issues/575#issuecomment-3042429677)
- [ ] Separate and categorize pages per env and namespace (blocked by https://github.com/EmmyLuaLs/emmylua-analyzer-rust/issues/575#issuecomment-3042429677)
- [ ] Ensure https://github.com/beyond-all-reason/RecoilEngine/issues/1430 is taken care of
- [x] Do not render helper/alias types on listings/nav
- [x] Lack of type linking, e.g. a method returns `UnitState` it should link to the `UnitState` definition.
- [x] Params are referenced only by the name and do not show they type
- [x] Tables are not expanding to their fields, e.g. `Platform` or `Engine`
- [x] Overloads, while probably the best way to handle definitions with conditional params and returns, are presented poorly. See how documentation references on languages that natively support the concept of overloads handle this. Example low-hanging-fruit fixes: presenting the number of overloads on the first entry e.g. "function Spring.Bla _(+n overloads)_", don't repeat the same description on all overloads, assume the first already explained the general function description and only lists what the new overload does, etc
This can be separated in other issues, but for now it's a reference we can work on.
Contributor guide
Research direction
Start by reading the generated-documentation checklist and the linked issues 1430, 1204, and 1959, along with the referenced EmmyLua analyzer blockers. The issue has no named files, tests, or single entry point; it is done only after the broad checklist is split into scoped changes with separately verifiable outcomes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100