beyond-all-reason / beyond-all-reason/RecoilEngine

Improve docgen accessibility

Open
#1,958 6 comments 1 reaction 0 assignees View on GitHub
area: documentation
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.