5 ms·
The Rust documentation is deep but not wide: unlike Python (for example) the standard library is small, which means that the well-documented area is small. Almo
by whatshisface 8y ago
The Rust documentation is deep but not wide: unlike Python (for example) the standard library is small, which means that the well-documented area is small. Almost as soon as you try to get anything done, you will end up reading auto-generated function signature docs and browsing through the source code of whatever crate you want to use. This is true for scientific computing and game libraries, and may not be true for networking which I hear is very well-developed.
Because Rust's type system is so good, auto-generated function signatures are actually pretty useful. However this is one area in which the language is clearly immature.
- melling 8y agoThat's what Perl programmers used to say about Python. It couldn't compete with the CPAN library. While a large set of libraries is helpful, I wouldn't let that stop you if you think Rust is a good fit for your problem.
- dnautics 8y agoTo be honest, python libraries are wide but the documentation quality isn't always the best (I could be spoiled)
- cpach 8y ago”documentation quality isn't always the best” Compared to what? (Asking just out of curiosity.)
- 4thaccount 8y agoIn general, I find Perl's CPAN to usually have really good documentation that surpasses what Python has, even though I prefer Python over Perl nine times out of ten.
- kbenson 8y agoAs a full time Perl developer, I've wondered more than once if this is due to the way the way the language shapes the community. Perl has evolved (out of necessity) a very strong level of norms and best practices that users are aware of, and put effort into following (well, most the time, Perl is all about letting you pull out the shiny weirdness and letting it shine where it fits well). Module documentation is part of this. A module could implement an object oriented interface, a procedural interface, both, import function into the main scope on use, or on request, or any number of weird (and depending on your point of view wonderful) things. Not having good documentation means nobody knows how to use your module without a lot of work reading the code. So modules get documented or they get ignored. Thus, the modules on CPAN you know about and that are commonly used and relied on by other modules are the ones that have good documentation. It's self reinforcing. I imagine in a language that funnels use into a single or small set of idiomatic ways to accomplish most tasks, it might be easier to skimp on documentation and rely on people to fall back on the "obvious" way to things.
- 4thaccount 8y agoI'm not a full-time Perl Dev like you, but do whip up something a few times a year and it is there when I need it. I'm therefore incapable of properly replying to your thoughts although it makes sense to me (Perl is so flexible that you better have good documentation if you make a module and want it used). My thoughts are more along the lines of how much modules and CPAN are pushed in general. Most of my Perl books (Ovid's in particular) go into excruciating detail on publishing packages. It's not a two pager crammed into an appendix either, but is front and center. The Perl community frequently hosts challenges to clean up old modules and such. There is even a guy with the last name of "Anwar" if I recall correctly that is a celebrity in the community for how many modules he maintains that aren't even his (and he has also done challenges like making a new pull-request every day for like a year). That is some real dedication there to making Perl useful. It is one of the things I really like about the community. I'm a little bit of a language hobbyist even though I'm still only a novice coder in my mind. Out of all the languages that I've spent time with (probably 2 dozen) learning superficially, I'd say Perl ranks towards the top of the spectrum when it comes to focusing on this. They've evolved a relatively simple and effective system for allowing users to make, share, and document libraries.
- dnautics 8y agoCheck out docs for elixir. It's a community where the standard library docs set a high standard of quality that quite a few package developers seem inclined to try to aim for. Heck, the documentation for the Float module even is kind enough to warn you about gotchas in IEEE floating point. https://hexdocs.pm/elixir/Kernel.html https://hexdocs.pm/elixir/Kernel.html One thing I really like: Unlike in python docs, on all the function calls and most module headings you can click through to the actual elixir source code and see how the functions work under the hood (via the <\> link). You also get this nearly for free when doing docgen on your own modules (it's one line in setup). Also, the HTML is responsive so it's easy to review your own code when on the toilet, if necessary. And there are python libraries that are horrible offenders. Perhaps it's a matter of taste or experience, but I found the tensor flow docs to be inscrutable and nearly useless
- dan-robertson 8y agoI’ve found latex packages often have quite good documentation. Sometimes elisp packages have good documentation but sometimes they don’t.
- deleted 8y ago[deleted]
- steveklabnik 8y agoWe’ve been trying to figure out how to improve this, but it’s tough.
- Twirrim 8y agoFeels like solving a cultural problem.. but one that affects a large part of the software development community. The aversion to writing documentation seems pretty deep set in most developers :)
- dodobirdlord 8y agoPerhaps I'm missing something obvious, but cannot a large part of this be addressed by significantly expanding the standard library? A favorite feature of mine in AWS CloudFormation is the ability when writing Lambda functions for the Python runtime to inline the code into the template and sidestep the process of generating and uploading code artifacts. This works because other than the (provided) boto3 SDK, I generally need nothing but the standard library. https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-lambda-function-code.html https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGui...
- dan-robertson 8y agoPutting things in the standard library can greatly slow down their development as it upgrades when the standard library does and deprecating things can be more painful for library users because it is much easier to choose an older version of some boring library than of the standard library. Then again, maybe one would want such things to slow down development
- turbinerneiter 8y agoThere is probably a _right time_ to start pulling more libraries into the standard library.
- steveklabnik 8y agoThat comes with all of the downsides of significantly expanding the standard library.
- est31 8y agoRust at least has auto-generated documentation. Python lacks that. Some python libraries might have documentation up, but there's no docs.rs like thing where you can just find docs for (almost) every library available.
- floofy222 8y agoI feel that the quality of auto-generated docs is generally better for Rust than for other languages like C++ (e.g. via doxygen). This is because the tools make it trival to publish and distribute docs for your crate, and people make use of that because it is so easy. Obviously, these tools don't solve the problem for you. In the same way that some C++ projects use doxygen without writing doc comments and say "but we have auto-docs!", some Rust projects (the rust compiler libraries and official projects, e.g., cargo, libsyntax, etc.) almost completely lack API docs. They do have books (rustc book and implementors guide, cargo book, etc.) so it isn't that they are completely undocumented, but if you want to use these as libraries, the auto-generated API docs are useless.