4 ms·

I really like the way documentation works in Rust: You basically write markdown in a special type of comment over the module, function, datatype or method you w

• cjfd 3y ago
  I don't have experience with this in Rust but have come to passionately hate this kind of documentation in other language. I think all of pydoc, javadoc and, doxygen are all garbage. If one could apply them sensibly it would not be so much of a problem but then you have documentation nazis who force you to document every method and every parameter. This leads to hightly enlightening prose documentation that the get_height method "gets the height", and that its return value is the height. A more high level problem with this is that you get documentation that is just as fragmented as the code and where the high level usage of things is not explained at all. Also it clutters the code with many highly trivial remarks.
  • Karrot_Kream 3y ago
    Yeah this is why I love literate programming. Being able to read a program with "narration" is so much nicer than just reading documentation piecemeal. Maintaining literate programs though is a quite difficult because you have to figure out where new code or changes fit in the overall narrative. I have a scraper I wrote in literate style and I only have to change it yearly. Each year I forget what I wrote and then I reread the program and make the necessary changes.
    • bayindirh 3y ago
      Literate programming is great until your code base becomes unwieldy. Then you need a README.md file which acts like a pointer to the correct entry points. Then as the code grows, you need to document the architecture, add small gotchas, etc. At the end of the day, documentation wins.
    • atoav 3y ago
      I am very code literate, but depending on the size of the codebase and how much smoke and mirrors are used, I might take longer to grok how things are interconnected by reading the code than it would take me if someone gave an high level overview in a paragraph or two.
  • c00lio 3y ago
    I am a documentation nazi. I hate it when people skip over documentation because something is obvious or trivial to them. Stuff isn't obvious or trivial to people who have to use your code. get_height gets which height, outer or inner? Are there error values, e.g. 0 as "don't know any height"? Does it have side effects? Is it a stable and reliable part of the API or bound to change soon? Is it thread safe? Will it change any of its parameters? Who deallocates the return value? Do you need to hold a lock somwhere? Of course it might be a good idea to group together get_height, get_width, get_diagonal and get_depth if the above is all the same for those. But having no documentation just because you think it is trivial that get_height gets some height from somewhere just means that you are sloppy and didn't think of all of the above. So your code shouldn't be touched with a 10-foot-pole imho. My solution, which I personally hate but know of no alternative to, is a documentation template for each function asking the above questions (depending on runtime and language of course) that I give people to fill in. Until they learn...
    • kristiandupont 3y ago
      It's true that there can be gotcha's in code which should be documented, but I don't think forcing a template on people is the solution. In fact, I wouldn't expect people to be better at documenting them with that in place.
      • c00lio 3y ago
        Well, yes, you need to have manual or automatic checks for the presence of the template, and the correctness of the contents is often uncheckable by automated tests. But if things break and e.g. the filled-in documentation template incorrectly said "thread-safe: yes", it will be very easy to 'git blame' the culprit. That way you can at least slowly weed out the sloppy documenters, but I admit that this is tedious. And, yes, I don't like this either and would like a better solution. But so far I didn't get any viable suggestions.
    • frde 3y ago
      Most of what you described as needing documentation could be expressed as code (mixing multiple languages here to express the point more clearly) const fn get_outer_height() -> Result<SomeErrorType, WeakReference<Number>> - `const` makes it clear this doesn't mutate - the function name says exactly what it does - The return type makes it clear it can return an error - The return value is typed in a way that makes it clear what the ownership is Throw in a language like Rust that gives guarantees about thread safety and now the only thing left is if the API is stable or not. Which I would argue doesn't matter much at all since people will still end up depending on it regardless of the comment saying "This API might not be stable" And the best part? My definition will never get outdated. If the assumptions change, the definition will also need to change (well, except for maybe the name)
  • marcosdumay 3y ago
    I am firmly on the opinion that every bit of public interface should get a documentation string. You say "gets the height" is trivial, but that text tells not only what the function does, but also that the author couldn't think of anything else important to say. This is very different from no text at all, where you can't be certain if the author even thought about it. IMO, enforcing an internal structure (AKA "you must document each parameter and the return value") is counter-productive, but enforcing the existence of the comment is very productive. > Also it clutters the code with many highly trivial remarks. I'd say that it "clutters" the code with markers for public elements and hard to understand ones. Those are actually valuable, and not clutter at all. Anyway, if those markers are a large share of your lines, you may need to rethink your architecture. It's usually not valuable to have a lot of interface for trivial things.
  • jononomo 3y ago
    You've put your finger on exactly why I don't like this kind of documentation. Also, I don't tend to trust it as much, because it isn't actually what the program executes. When I'm trying to read the source code I don't want to read about the source code -- I want to read the actual source code -- and if I keep coming across long multi-line idiotic comments then it breaks my flow and concentration. I like the source code itself to be extraordinarily readable, with long and descriptive variable and method names, but I want it to be dense and packed into paragraphs of sense. To the extent there are any comments at all they should be extremely short and completely clarifying -- they should not even partially overlap with information conveyed through function or variable names, for instance.
    • atoav 3y ago
      > Also, I don't tend to trust it as much, because it isn't actually what the program executes. Maybe you don't know Rust, but it is a strongly typed language. If you go to a rust project and run `cargo doc --open` you will see exactly what the type system lays out. Sure if someone writes "changes the windows height and returns a new Window" on a change_window_height(height: Pixels) -> Window and it changes the windows width instead that is still wrong. But (A) you can click on "source" and see the actual code and (B) you are guaranteed that the function takes Pixels and spits out a Window That being said I hate that kind of documentation in most other languages, not in Rust. In Rust it is basically an alternative view onto the same code with a (needed) emphasis on the realtions of the entities the type system describes. If there is prose that can be a nice extra, but cargo doc is even useful without a single comment.
  • atoav 3y ago
    I understand the sentiment, because I hate this in other languages too. But somehow in Rust it works. Of course there is also bad documentation of the kind you describe, but that is a different problem. Bridging the gap between a prosaic high level explaination (how do the parts work together?) and a fine grained explaination of each part (what does that part do?) can be a challenge. Rust solves this somewhat by allowing you to do module level documentation (that can essentially look like a blog post, only that the examples get checked when the code is tested) and it lets you link to different entites. I would always prefer a well written blog post, if people were able to keep the examples working and the code up to date. But experience shows they are not. I'd rather have generated documentation that is true than a blog post where half of the examples won't work, because nobody bothered to update the post after the code changed. The first might at times be barren if done badly, the latter is downright misleading.
• hitchstory 3y ago
  I built a testing library on top of pytest based upon the idea of doing this mapping at an application level instead of a method/function/class level. If you write tests in a strongly typed, non-turing complete markup (in this case, StrictYAML), you can then use it with a template and test artefacts (e.g. app screenshots) to generate readable how-to/tutorial docs which are guaranteed to stay up to date. https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory This isn't a new idea, but I find that people are often skeptical because there's a history of people getting their fingers burned by Gherkin's language design or YAML's weak typing (both of which are completely valid).
• barrkel 3y ago
  This is API reference documentation. What you're missing is conceptual documentation and use case examples. Conceptual documentation, the big picture, is important to convey the mental model implemented by an API. In applications, you can generally infer it from using the app, but it's not always easy, and it's indirect. Use case examples string together multiple APIs, multiple domain objects, to achieve a high level business objective. When working on a project, you can sometimes get away without this - the existing code can be example enough to copy. You can end up with cargo culting, people copying things without understanding why. But if you have an API for third-party use, which needs documenting, you need to have either a well-seeded set of open source users, or a great set of examples.
  • Gwypaas 3y ago
    Rustdoc supports conceptual documentation quite well, including testing the example code. A specialized page is better, but the pareto principle applies. See the Clap documentation: https://docs.rs/clap/latest/clap/ https://docs.rs/clap/latest/clap/
  • paddy_m 3y ago
    I often call this narrative documentation. It's the antidote to Chesterton's Fence and explains the thinking of the programmer who created the thing. How did that programmer expect people to use their tool.
• manicennui 3y ago
  Most popular languages have a version of this, including Java. This is only one level of documentation, and one must know a bit about what they don't know to use it effectively. In other words, if you already know that you need to use the foo function, then the foo function's documentation is great. If you don't even know which function or class/module to use, it isn't a great starting point.