Subdoc TODOs

[danakj]

• Generate namespaces
• Generate functions
• Generate methods
• Generate fields
• Generate static members
• Show template params
• Show requires clauses
• Nested classes missing in Subdoc #432
• Generate Concepts
• Generate Typedefs, and chase through simple using n::T typedefs (UsingDecl) if code links (from fn signatures etc) point to them when generating. Don't chase through more complex using F = n::T<U> (TypeAliasDecl).
  • Generate aliases to enum constants (using enum E, using sus::option::State::Some)
  • Generate aliases to global variables (sus::empty, sus::marker::unsafe_fn)
  • Generate aliases to methods in base class
• Generate enums
• Generate Macros
  • Macros without comments are skipped, generate them too.
• Generate global variables (sus::marker::unsafe_fn)
• Represent UDLs nicer, instead of operator""_i32 it can say _i32 literal or _i32 UDL or something.
• Generate links by C++ path instead of hand-writing html paths. This is better for refactoring search/replace and can detect broken links to produce errors at generate time. Probably make a markdown extension like $[foo](foo) or something. Code links #323
• Left side menu for all the stuff in a page for faster navigation and knowing what's there
  • Namespaces
  • Records
  • Concepts
  • Functions
• Pull apart types into a data structure that can be used to generate the type as a string again but also can turn types inside the type (template args etc) into links.
• Pull apart requires clauses into a data structure that can be used to generate the type as a string again but also can turn types inside the type (template args etc) into links.
• Handle markdown parser errors
• Special case support for Choice?
  • Private types in Choice signature don't get linked, and are thus loud (all the path is written out) and confusing.
• Add a #[doc.include=path/to/file.md] attribute and a --include-root ../.. command line argument. Then drop the special case for the project.md file in the global namespace? But where would we write the comment to #[doc.include] into the global, maybe it has to stay. Anyway it would let us write namespace level docs in a Markdown file which would be nice, and reuse the same docs in multiple places.
• In-site search, generate a search db and use it.
  • https://pagefind.app/ recommended
• Show a project version somewhere (in the left menu that doesn't exist yet probably?)
• More terse code links like rustdoc, see On terse code links
• Syntax highlighting of examples/codeblocks
• Compiling examples during generation (which requires hiding code in examples such as #include and which rustdoc also supports)
• Links to code from each database element such as function/type/concept/etc. With a command line argument to the root of a web git repo in order to generate source links. We can use github anchor format (#L20) but it can be configurable to put the L in the anchor or not.
• Observe static asserts to mark types as satisfying concepts.
  • Straight forward for non-template types, if the assert is there, it's satisfied.
  • Provide a means to specify to the doc tool that a static_assert of a concept with a template type is true for all instantiations of that template type or not. Ideally with a dependency on another concept, like "true if the template parameter T satisfies Eq". One idea here would be to provide specific types that do satisfy those concepts and act as markers to subdoc to represent it, but subdoc can't know about all concepts. Another idea would be to specify it entirely through doc attributes but that can get out of date. Another idea would be to specify "this type represents satisfying this concept" to subdoc through a doc attribute, then whenever subdoc sees it in a static_assert it can use it for that role.
• Class template specializations
  • All the specializations of fmt::formatter and TryImpl and ErrorImpl and TransmogrifyImpl etc are not rendered at all. How to render them but associate them with the class named in its specialized template parameter? The fmt ones aren’t even collected into the db since its just associated with the fmt class.
• An "All Items" view
• Add headers so that links show the description/title/icon/url all correctly (tested on mastodon and discord).
• Show deleted class methods
• Mark functions as constexpr without just putting the keyword into the signature.
• Show if a constructor is explicit or implicit.
• Show aliases of a type/fn on the type’s page. Like sus::construct::cast should show that it’s aliased as sus::cast.
• Possible to make ctors more clear in the left side menu by including something more than their name, while still keeping it short?
• Move friend functions declared in a class into the class's page?
• If the first constraint on a function is a concept constraining the first parameter, move it up into the definition of that parameter. If so, then same for 2nd, etc.

On terse code links

Rustdoc just requires

[`Type`] or [`Type::method_or_field`]

and it figures the rest out from what the context is (literally DeclContext for us) at the place where the comment is written. Then we don't need the ($cpp-path) syntax.

Except there's an open question there around how to link to a specific overload, so maybe we need like

[`Type`] or [`Type::method_or_field`] or [`Type::method`!overload-group]

or something.