Linux’s contemporary filesystem mount API went without documentation for six years — latest man-page package finally adds content for 2019 code

by

Linux's contemporary filesystem mount API went without documentation for six years — latest man-page package finally adds content for 2019 code

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 Contributor 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. 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. Reply

-Fran- 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. The man pages ARE user documentation as they document USAGE . 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. Reply

qxp Just want to add to the article that the filesystem mount API discussed is a C API, meant to be used by developers writing programs that need to mount or unmount filesystems. These are not commands used in a terminal. Thus I think it is perfectly OK that the developers of system level tools needed to read the implementation code or messages from API developers to find out how to properly use the API. And now that its been used for some time and stabilized it is being documented. Reply

Sam Hobbs 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. IBM documentation tends to consist of both a reference and a user guide. The user guide is intended for beginners and others that want an easier explanation and do not need the details. The reference is more technical. I think that if I had a choice of one or the other, I would choose a reference. It is possible to write a user guide from a reference but it is not possible to write a reference from a user guide. I think it is important that the man page documentation include all technical details necessary for the use of the software. Other (educational) documentation could be developed from that. ezst036 said: From no man to man to YouTube. I think you misunderstand what documentation is. YouTube is great for tutorials but useless for documentation. Now with AI it is possible for an AI system to analyze source code and create specifications. Documentation is much like specifications; the documentation could be developed from the specifications. Also, it is hopefully easier to read specifications than the source code. This might be an excellent opportunity to explore such solutions. The following is what Perplexity AI says on the subject. https://www.perplexity.ai/search/i-read-an-article-saying-that-SntxdNRaR.WqUlBeldUdug#0 Reply

Conor Stewart Good code does document itself but only to a point. Writing readable and understandable code should be a given but it should also have comments, at minimum what the function takes as input, what it does and what it returns as output and then adding on comments for any unusual or less understandable bits of the code. Then there should be user level documentation above that, they don't care about how it is implemented, they only care about what each function does and how to use it. A good example I have found is the STM32 Cube drivers, they bundle a HTML user documentation of the drivers. It includes things like public functions, variables and macros as well as private functions, variables and macros. In order to use it the public sections are often enough, clear documentation on data structures and function definitions and what they do. I wouldn't class it really as a user guide as it isn't quite as clear as would be needed for that, but it is clear enough if you know what you are doing. Yes code should be readable and understandable but that doesn't mean it shouldn't have comments and documentation. Comments can speed up someone's understanding of your code and it takes much less time to just write a comment explaining your thought process rather than many people trying to figure out why you did what you did. Then documentation is even higher level and is for people who don't care how your code works, just that it works, which I would say is the majority of open source software users. In my opinion neglecting comments and documentation is just laziness. How often do programmers say that when they go back to code they have written previously they basically have to decipher it from scratch? Or at the very least need to take time to understand it? That should tell you something. It shouldn't need you to go right through all the code in an open source project to understand why it is done that way or what each function does. As with any engineering discipline other than software engineering, logs and explanations are essential and often non negotiable. You need proof that you thought through it. In current software engineering you can essentially say that this random piece of code that I just spewed from my brain passes all tests so it is fine. I honestly believe that readable and understandable code being enough is not completely true, yes it might be enough to understand the code, but if your colleague comes to check or change something then it likely ends up taking more time than just writing comments as you go. In programming the time consuming it is not typing, it is thinking, so typing out your thought process really doesn't slow things down and can actually increase your productivity. It is like that saying that the best way to learn something is to teach or explain it. Reply

Key considerations

  • Investor positioning can change fast
  • Volatility remains possible near catalysts
  • Macro rates and liquidity can dominate flows

Reference reading

More on this site

Informational only. No financial advice. Do your own research.

Related posts:

  1. Linux’s contemporary filesystem mount API went without documentation for six years — latest man-page package finally adds content for 2019 code
  2. Atari 2600+ Pac-Man Edition released at $169 — bright yellow console comes with Pac-Man: Double Feature 2-in-1 game cartridge
  3. Atari 2600+ Pac-Man Edition released at $169 — bright yellow console comes with Pac-Man: Double Feature 2-in-1 game cartridge
  4. Atari 2600+ Pac-Man Edition released at $169 — bright yellow console comes with Pac-Man: Double Feature 2-in-1 game cartridge

Leave a Comment