Linux's contemporary filesystem mount API went without documentation for six years — latest man-page package finally adds content for 2019 code
Something something good code comments itself.
Core system code doesn't move at quite the same pace as the latest vibe coders, and thankfully so, as it needs to be stable, efficient, and battle-tested. However, sometimes delays can get a little ridiculous, as was the case with the documentation for Linux's contemporary filesystem API. As noted by Phoronix, it was over a six-year wait for the info to appear in the standard man-page (manual page) documentation.
The tale goes like this: in 2019, Linux got the minty-fresh new filesystem mounting API, with the main "fsconfig," "fsmount," and "fsopen" calls replacing the old, monolithic "mount." This made it a lot easier for developers to use the new functionality, enjoying cleaner code, better error handling, and the ability to output proper error messages, rather than the cryptic "mount failed."
Developer David Howells wrote drafts of the man-pages in 2020, but those were never merged to the man-pages package, as the maintainers didn't want to include potentially incomplete or imprecise drafts. Howells apparently couldn't complete the work, and nobody else stepped up.
During the following years, developers wanting to use the new system would have to dig through an ugly file in the kernel source code, find discussions in the Linux kernel mailing list, or enjoy reading through dozens of patch notes. At the best of times, external websites actually contained a how-to of sorts, given the situation.
Another reason for nobody stepping up to write new man-pages was that the standardized format is Groff, which is now 35 years old and is so human-unreadable that it might as well have been written by Cthulhu.
Documentation master Christian Brauner got fed up in 2024, stating "years of writing Groff have made me tired," and he created his own repository with Markdown version of the pages, finally giving developers the one spot for finding the necessary information. Finally, as of October 2025, the official man-pages package now contains these pages.
It's somewhat plausible that the almost-missing documentation might have contributed to the long delays of multiple filesystem handlers using the new API. Good ol' Ext4 only used it in 2022, CIFS (SMB) did it in 2023, Btrfs was late to the party in 2024, and F2FS's (flash filesystem) implementation is still in progress. The new man-pages have yet to find their way into common distributions, so only rolling-release types will have them.
Get Tom's Hardware's best news and in-depth reviews, straight to your inbox.
Follow Tom's Hardware on Google News, or add us as a preferred source, to get our latest news, analysis, & reviews in your feeds.
Bruno Ferreira is a contributing writer for Tom's Hardware. He has decades of experience with PC hardware and assorted sundries, alongside a career as a developer. He's obsessed with detail and has a tendency to ramble on the topics he loves. When not doing that, he's usually playing games, or at live music shows and festivals.
-
-Fran- It's important to make this distinction: code being "clean" (readable, maintainable and beautiful) is not the same has having documentation at the functionality/higher level. The code is not user documentation! This phrasing is mostly for comments and other in-line helps: if you need to explain it, then it's not clear enough (readable or maintainable). I'm not an extremist when it comes to comments, as sometimes decisions/approaches need an explanation (outside of immediate code scope context) so it's not changed in a way which would break things.Reply
Whenever a developer gives me the "my code is good, so I don't need to document it", I send them to the Gulag.
Regards. -
ezst036 Reply
This is a pretty big bugaboo and it is kinda widespread within the Linux realm.-Fran- said:It's important to make this distinction: code being "clean" (readable, maintainable and beautiful) is not the same has having documentation at the functionality/higher level. The code is not user documentation! This phrasing is mostly for comments and other in-line helps: if you need to explain it, then it's not clear enough (readable or maintainable). I'm not an extremist when it comes to comments, as sometimes decisions/approaches need an explanation (outside of immediate code scope context) so it's not changed in a way which would break things.
Whenever a developer gives me the "my code is good, so I don't need to document it", I send them to the Gulag.
Regards.
This is pretty much true of the man pages themselves as well. The man pages are not really user documentation either, they're "techie" documentation and usually for more-techie-than-average techies at that. Software developers become a special breed, gaining the ability over time more to speak to their computers but that comes at a cost: losing the ability to speak less and less to normal humans.(Note: This is definitively NOT to be read as an insult.)
From time to time I see someone ask how to do X and the response is RTFM. Not realizing, I read the man! It didn't help. So that is why I came here now to ask you to break it down human to human for me instead of the awful man pages.
I think this may at times lead into a larger problem of keeping the myth alive that Linuxes are all still terminal based systems and nobody ever heard of a GUI. Go to YouTube and how many times do you see someone with a Linux desktop and the very first thing they do is open a terminal when right there on their menu, you can see it. Click the button. Click the button. WhY aReNt YoU cLiCkInG tHaT bUtToN rIgHt ThErE i CaN sEe It In YoUr ViDeO! I don't want to see your terminal I want to see you click the button. Just click the button. It's right there!!! ARG! Why are you intentionally making this more difficult? sigh.
Well, there goes my little rant for the morning.
Improper documentation, it's a problem at all Linux levels. From no man to man to YouTube. -
-Fran- Reply
The man pages ARE user documentation as they document USAGE.ezst036 said:The man pages are not really user documentation either, they're "techie" documentation and usually for more-techie-than-average techies at that.
Anything that tells you how to interact or USE a piece of software is "user documentation". Anything that talks design or even "code", then it's a design/architectural document. I don't even want to go down that rabbit hole, since there's several different approaches there and ways to accomplish the same end-goal: explain how things are built and maintained.
You can use any other internal labels you want, but at the most fundamental level, it's just "user documentation". Documentation, in the broader sense, has many different facets and your target audience defines both the content and writing style. So I half agree with your semantic distinction to call the man pages "techie user documentation", but never forget they are still "user" level documentation for a very specific target audience.
Regards.