Hah! Do you have a running search giving you alerts when lmdb is mentioned or something?
> How is doxygen a disaster?
I've just never read any good, user friendly documentation ever produced by doxygen. Even when I used it myself. It always comes out looking like a pig's breakfast.
Like, take the lmdb docs. And I'm sorry for picking on it. But its a good example, because you've clearly put effort into using doxygen to document lmdb. I think the lmdb docs are about the best that doxygen generated documentation gets.
Looking at this page: http://www.lmdb.tech/doc/group__mdb.html
There's a bunch of concepts here:
- Environment (mdb_env)
- Database and database (dbi)
- Transaction
- Cursor
- Record
- Key
But none of those concepts are defined or explained. They're simply referenced without explanation in a big jumble of function names and descriptions, leaving me to figure out how they're supposed to work together. Maybe if those data types were defined up the top of the page? No. Doxygen tries to put some data structures at the top of the page - but for some reason the only documented types are MDB_val, MDB_stat and MDB_envinfo. All terrible places to start reading if you want to understand how to use lmdb.
Good documentation would lead with some front matter like:
- What does the library do
- How does the library sees the world. Here, explain the above concepts and how they relate. (Eg an environment represents a set of files on disk. Each environment contains a numbered set of databases, database contains a set of records. You can read and write within a txn. You can use a cursor to iterate. ... Etc)
- Code examples of all of the above. Ideally a hello world, and more complex / specific examples showing each feature.
Doxygen does not help with any of that. From this documentation I don't know how to use lmdb to make a correct program. I can kinda guess how to use various features, but not what the features actually are or how to use them correctly.
For example, I can obliquely tell from reading the function descriptions that an environment can be opened multiple times at the same time. But I have no idea why I'd want to do that, or how, or what performance implications there are, or if there are any gotchas I need to be aware of if I do that. I see there's a bunch of functions for mdb_env_copy. Does that copy in memory or on disk? Does it do it atomically, like at a snapshot? Is it synchronous? Does it fsync? fdatasync? What errors can happen? The documentation isn't helpful.
So I'm not just banging on about rust, here's equivalent - but much better - reference documentation for prisma:
https://www.prisma.io/docs/orm/reference/prisma-client-refer...
Prisma also has a separate guide, explaining the concepts involved:
https://www.prisma.io/docs/orm/prisma-client/queries/select-...
Or for another positive example, here's bun's documentation on using sqlite from javascript:
https://bun.com/docs/runtime/sqlite
They explain the concepts and present examples for how to use all the features. When I read those docs, I come away knowing how to use the library to solve my problems. I don't have that experience reading the lmdb documentation.
Maybe its possible to produce good documentation using doxygen. But I've never seen it done. Not even once.
-----
Side points:
> you should already be reading the source code on your local machine.
I'd rather not read the source code of all my dependencies to understand how to use them. Reading the source code of your dependencies should be a last resort. Eg, I don't go reading my compiler's source code if I want to understand my programming language. I don't want to read the source code of my web browser, or postgres, or linux, or any of this stuff.
> It makes no sense to go searching across the web for information that's already stored on your local machine. Especially since you have no idea if the version you find on the web matches the version you're using locally.
I hear you, but honestly I don't really care where documentation lives. Just so long as I can find it and read it. But with rust in particular, if you want local documentation you can run cargo doc to generate & open the documentation of your project and all your dependencies, which is nice.
And re: versions, rust docs hosted online also have a little 'version' field up the top showing which version of the library you're looking at the documentation of. Eg if you open https://docs.rs/rand/ I see "rand-0.9.2". If you change versions, the URL changes. It'd be nice if doxygen had that too.