Consider adding in-code documentation

[randoragon]

Man pages will stay 100%, because they are a unique selling point in a world rid of simple, old solutions. However, I would like staple to integrate well with LSP clients, because those are the de facto status quo, even in editors like neovim. Furthermore, it would be nice to be able to generate an html documentation for online viewing, if I decide to take that step.

I haven't explored this topic much, I'm pretty sure Doxygen is still the standard for C code documenting. But I've never tested how well it integrates with LSP.

Another consideration: Maintaining Doxygen and man pages separately would be a huge pain. Doxygen has a man page output option, but I don't know how good it is. If it's no good, then it could be necessary to create my own format, which is also a lot of work.

[randoragon]

Extra remark in case it wasn't obvious: C is a compiled language, so the in-code documentation would only extend to header files which are exposed to the user.

[randoragon]

When I originally wrote this issue, I was just beginning to integrate LSP tools into my neovim workflow. I've since come a long way and now I firmly believe good LSP hover support is indispensible for any modern C library. I will definitely look into ways of achieving this. I would like for man pages to stay, because they are cool as well. But I think my priorities are shifting towards LSP support more.

[randoragon]

I've done a bit of digging on the following tools:

1. doctools (with its tcl-implemented processor dtp)
   • too niche, implemented in TCL, it can generate man pages but not sure if it would fit the bill 100%
2. doxygen
   • might be the way to go.
   • i have some gripes with clangd not displaying the comments nicely, but work seems to be underway: Doxygen parsing missing clangd/clangd#529
3. docbook
   • XML format, meaning keeping in-code documentation is impossible
   • does not seem to get a lot of traction these days? (https://github.com/docbook/wiki/wiki) it's a bit confusing
   • claims it can generate man pages, html, pdf, text, anything

---

Key take-aways from me, going forward into the project:

1. Documentation must be in-code. It should be embedded directly in template files, from which source files are generated (luaparser).
2. LSP hover support on a struct/function name to get all information about it is a must. Preferably should work also for header file includes.
3. Ability to generate HTML is a must, because in the future I would like to be able to host documentation online.
4. Man pages are nice, but not necessary. If at any point supporting man pages should hinder the implementation of the above 3 goals, they should be ditched without hesitation.

I believe doxygen fills the quota on all of these, and given its popularity it should be a safe, future-proof option. That's where I would start further work on this. But for now this issue is not high-prio.