4 ms·

I'm kind of intrigued how widely opinions differ here. I consider the Rust docs here dramatically better due to their focus on soft documentation. I can't stand

I'm kind of intrigued how widely opinions differ here. I consider the Rust docs here dramatically better due to their focus on soft documentation. I can't stand Java docs.

imtringued 7y ago
References are not meant to provide "soft documentation". Guides are supposed to do that.
- dfinninger 7y ago
  I personally prefer Rust's style here to Java, and a good deal over C++. I had to learn Java last year and--even as an experienced programmer--the guides we're pretty miserable. The info was there and it was terse [1], but I wound up paying for a course elsewhere because the official docs weren't working for me. Rust method here of combining the guide (Struct docs) and reference (Methods) is vastly superior, in my opinion. One niggle I always have with docs is that the two things are considered separate and I have do figure out which link is the one I'm looking for. God help me every time I need to find the String functions in the Python docs. If you don't like looking at the guide in the Rust docs, click the "[-]" in the upper right. It'll collapse everything in the page and make it look a lot more like the C++ sample. [1] https://docs.oracle.com/javase/tutorial/java/data/strings.html https://docs.oracle.com/javase/tutorial/java/data/strings.ht...
  - jnordwick 7y ago
    It is way too difficult to find a function you don't know exists, and I'm not going memorize the api. It doesn't even come remotely close to the CPU docs. It isn't sectioned just a dumb list of methods where similar methods can be pages away from each other (eg all the methods to look up or index into a data structure should be grouped). Maybe I just have a higher standard than most rust users.
- jzoch 7y ago
  I (and i'd assume many others) am not interested in pulling up references AND guides to figure out what I want. Rust has a 1 stop shop that not only tells me WHAT I can do but HOW with examples. Javadocs is horrible in that I see a method I want to use and then have to google for an example on how it is used. Rust >>>>>>>>>>>> Java in this regard.
jnordwick 7y ago
Not even a useful softdoc though. Let's say I need to search then mutate an data structure. There are probably number of ways to do what I need. Right now, it is almost impossible to see what my options are. And I'm not going to memorize the API either. Sorry.

I'm kind of intrigued how widely opinions differ here. I consider the Rust docs here dramatically better due to their focus on soft documentation. I can't stand Java docs.

imtringued 7y ago

References are not meant to provide "soft documentation". Guides are supposed to do that.

dfinninger 7y ago
I personally prefer Rust's style here to Java, and a good deal over C++. I had to learn Java last year and--even as an experienced programmer--the guides we're pretty miserable. The info was there and it was terse [1], but I wound up paying for a course elsewhere because the official docs weren't working for me. Rust method here of combining the guide (Struct docs) and reference (Methods) is vastly superior, in my opinion. One niggle I always have with docs is that the two things are considered separate and I have do figure out which link is the one I'm looking for. God help me every time I need to find the String functions in the Python docs. If you don't like looking at the guide in the Rust docs, click the "[-]" in the upper right. It'll collapse everything in the page and make it look a lot more like the C++ sample. [1] https://docs.oracle.com/javase/tutorial/java/data/strings.html https://docs.oracle.com/javase/tutorial/java/data/strings.ht...
- jnordwick 7y ago
  It is way too difficult to find a function you don't know exists, and I'm not going memorize the api. It doesn't even come remotely close to the CPU docs. It isn't sectioned just a dumb list of methods where similar methods can be pages away from each other (eg all the methods to look up or index into a data structure should be grouped). Maybe I just have a higher standard than most rust users.
jzoch 7y ago
I (and i'd assume many others) am not interested in pulling up references AND guides to figure out what I want. Rust has a 1 stop shop that not only tells me WHAT I can do but HOW with examples. Javadocs is horrible in that I see a method I want to use and then have to google for an example on how it is used. Rust >>>>>>>>>>>> Java in this regard.

jnordwick 7y ago

Not even a useful softdoc though. Let's say I need to search then mutate an data structure. There are probably number of ways to do what I need. Right now, it is almost impossible to see what my options are. And I'm not going to memorize the API either. Sorry.