Hi all, I read the "docs as code" blog post recently, and found this idea resonating with my previous attempt to write wiki-style code documentation. Zef said in the v2.9 release post that suggestions for use-cases for the Object Graph are welcome, so I'm sharing mine here.
What I had in mind was a code documentation that has a similar folder structure to the source code, and uses wiki-links, yaml attributes etc. to connect each source file.
Conventionally, the "table of contents", i.e. tree structure, of docs is often different from the folder structure of the source code. There are often two parts of documentation, one is written like a book (tutorial first, then dives into some specifics or advanced topics), the other is "API reference" which is often automatically generated from the comments in function definitions in the source code.
This two-part structure requires the maintainer to keep the book-ish part align with the API reference part, and this task can be tiresome after refactoring or other big changes take place. It might be good for both the maintainer and the user to have a unified documentation which builds gradually on the function references.
To be specific, each note will have its title exactly the same as the path of some source file, and the topic of this note will be to explain what happens in that source file. There can be various attributes, e.g. dependsOn, that relates this note to other markdown notes.
For static languages, this documentation can very easily generated by a LLM with access to a Language Server Protocol: it knows what a piece of source code does by reading, and it can learn the context from LSP queries. For not-so-static languages, the role of LSP can be played by plain-text search or Lua queries; this is not as rigorous as the LSP, but also works.
Now that mermaid libraries are coming, I can imagine writing Lua queries that return mermaid diagrams in this kind of documentation, and since all markdown notes have exactly the same folder structure as the source code, it becomes convenient to write the mermaid queries: the Object Graph that we query will share many structures as the source code, and the relative paths of markdown notes are also very clear (instead of being an arbitrarily decided book-ish structure).
With this motivation, it is perhaps sensible to consider polishing Lua Query functionalities and Relations definitions so that this kind of documentation can be quickly and reliably written. For example, allowing queries like "who depends on A and is co-mentioned by B in C".
).