4 ms·

I've run into this more often than I can count with Java based things. "Just look at the Javadocs!" You...you mean the auto-generated API descriptors that have

I've run into this more often than I can count with Java based things. "Just look at the Javadocs!" You...you mean the auto-generated API descriptors that have exactly zero usage information on them, and expect me to figure out how to piece things together just by type signature? That...that isn't how documentation works.

grimjack00 6y ago
You mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?
- andi999 6y ago
  We tried to buy some mechanical equipment which can be steered by a computer API. I asked for the doc beforehand. Got something like your example (10 pages of C header). I asked any better docs? Answer:'a real programmer would know how to use this' - well somehow they didnt manage to sell the device to us. Later they managed to email the comprehensive docs (which existed!), but we alread spent a much larger amount (without regrets) to the competition.
- wlesieutre 6y ago
  On the SwiftUI side, you might go digging in these docs for Previews, which are one of its biggest selling points: https://developer.apple.com/documentation/swiftui/previews https://developer.apple.com/documentation/swiftui/previews Take 30 seconds to read through that and the linked pages (that's all the time it will take) and see if you could figure out how to use a PreviewDevice to make your preview show a particular device. It will tell you all the ways to initialize a PreviewDevice struct (from many different varieties of String), but you'll have no fucking idea what to do with that object. And here's an actual code sample, via Paul Hudson: struct ContentView_Previews: PreviewProvider { static var previews: some View { Group { ContentView() .previewDevice(PreviewDevice(rawValue: "iPhone SE")) .previewDisplayName("iPhone SE") ContentView() .previewDevice(PreviewDevice(rawValue: "iPhone XS Max")) .previewDisplayName("iPhone XS Max") } } } It turns out what you need to do is pass the PreviewDevice instance into a previewDevice modifier that you've applied to your view inside a struct adhering to the PreviewProvider protocol. I don't think this docs page even mentions that the previewDevice modifier exists, let alone how to put any of these pieces together to configure and display a preview. You can find how to do this in tutorials elsewhere on Apple's site. But you can't find it in their documentation for Previews, because it's a bunch of automatically generated pages of function signatures with no explanation.
  - uryga 6y ago
    found something! kinda: https://developer.apple.com/documentation/swiftui/previewprovider/previews-swift.type.property https://developer.apple.com/documentation/swiftui/previewpro... an example for `PreviewProvider#previews` uses `.previewDevice("iPhone X")`, and i'm guessing that that string gets turned into a `PreviewDevice` via one of those `fromBlahLiteral` methods it implements? my guess is that `PreviewDevice` is some kind of opaque handle thingy (which is why it has no visible members/methods) but that... really should be documented
    - wlesieutre 6y ago
      Good find! For some reason buried two levels deep from the Previews page. I believe you're right that it's silently building a PreviewDevice from the string. You can make the PreviewDevice explicit (as shown in the Hacking with Swift code sample), but nice tidbit that you don't have to.
- lostcolony 6y ago
  That I could probably look at the source and figure things out. No, what kills me is public Session getSession(Foo, Bar, Baz) where Foo, Bar, and Baz are themselves interfaces, and I have no idea what implementing class I need, so I go searching, and after an hour of pain piece together that I need to instantiate a NotAtAllAFooButNeverthelessImplementsFoo, then pass that into the BuildingFactory class' static factory method to get an instance of Bar, and then I can just pass in a null for Baz, and it -seems- to work.
j-krieger 6y ago
Rust and rustdoc (forget what it‘s called) have the same issues, sadly.
- Rotten194 6y ago
  rustdoc has the ability to embed usage examples in the doc comments, and automatically test them. also module-level documentation is doable via doc comments in the module main file. rust doesn't force you to write good documentation, but the tools are all there and I often see great documentation for rust crates that was generated with cargo doc. For example the Rocket docs are full of code examples on both the module and function level: https://api.rocket.rs https://api.rocket.rs I think there's something to be said for javadoc, cargo doc, etc encouraging documentation to hew closely to the structure of the code as opposed to a free-form documentation system that can include multiple pages about tasks, getting started, etc. But the vast majority of projects don't bother to set that up, and the javadoc approach makes it very low friction to add docs to existing code that probably already has comments explaining how to use it.
  - sidlls 6y ago
    That’s the barebones minimum, because in those contexts the examples are going to be relatively trivial. Often I find them to be no more helpful than the signature doc itself.
    - teknopaul 6y ago
      Even trivial examples that actually compile are better than none. because rust uses real code and markdown reading code and docs is the same thing in many cases, no need to even render to html, absolutely minimal markup noise. I love rust docs. Speaking from many years of using mostly poorly maintained javadocs and well maintained man pages.
freeone3000 6y ago
https://docs.oracle.com/javase/8/docs/api/java/time/Clock.html https://docs.oracle.com/javase/8/docs/api/java/time/Clock.ht... is a bit more involved than the autogenerated template. The Oracle documentation tends towards this level -- the javadoc template is simply where the docs are kept.

grimjack00 6y ago

You mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?

andi999 6y ago
We tried to buy some mechanical equipment which can be steered by a computer API. I asked for the doc beforehand. Got something like your example (10 pages of C header). I asked any better docs? Answer:'a real programmer would know how to use this' - well somehow they didnt manage to sell the device to us. Later they managed to email the comprehensive docs (which existed!), but we alread spent a much larger amount (without regrets) to the competition.
wlesieutre 6y ago
On the SwiftUI side, you might go digging in these docs for Previews, which are one of its biggest selling points: https://developer.apple.com/documentation/swiftui/previews https://developer.apple.com/documentation/swiftui/previews Take 30 seconds to read through that and the linked pages (that's all the time it will take) and see if you could figure out how to use a PreviewDevice to make your preview show a particular device. It will tell you all the ways to initialize a PreviewDevice struct (from many different varieties of String), but you'll have no fucking idea what to do with that object. And here's an actual code sample, via Paul Hudson: struct ContentView_Previews: PreviewProvider { static var previews: some View { Group { ContentView() .previewDevice(PreviewDevice(rawValue: "iPhone SE")) .previewDisplayName("iPhone SE") ContentView() .previewDevice(PreviewDevice(rawValue: "iPhone XS Max")) .previewDisplayName("iPhone XS Max") } } } It turns out what you need to do is pass the PreviewDevice instance into a previewDevice modifier that you've applied to your view inside a struct adhering to the PreviewProvider protocol. I don't think this docs page even mentions that the previewDevice modifier exists, let alone how to put any of these pieces together to configure and display a preview. You can find how to do this in tutorials elsewhere on Apple's site. But you can't find it in their documentation for Previews, because it's a bunch of automatically generated pages of function signatures with no explanation.
- uryga 6y ago
  found something! kinda: https://developer.apple.com/documentation/swiftui/previewprovider/previews-swift.type.property https://developer.apple.com/documentation/swiftui/previewpro... an example for `PreviewProvider#previews` uses `.previewDevice("iPhone X")`, and i'm guessing that that string gets turned into a `PreviewDevice` via one of those `fromBlahLiteral` methods it implements? my guess is that `PreviewDevice` is some kind of opaque handle thingy (which is why it has no visible members/methods) but that... really should be documented
  - wlesieutre 6y ago
    Good find! For some reason buried two levels deep from the Previews page. I believe you're right that it's silently building a PreviewDevice from the string. You can make the PreviewDevice explicit (as shown in the Hacking with Swift code sample), but nice tidbit that you don't have to.
lostcolony 6y ago
That I could probably look at the source and figure things out. No, what kills me is public Session getSession(Foo, Bar, Baz) where Foo, Bar, and Baz are themselves interfaces, and I have no idea what implementing class I need, so I go searching, and after an hour of pain piece together that I need to instantiate a NotAtAllAFooButNeverthelessImplementsFoo, then pass that into the BuildingFactory class' static factory method to get an instance of Bar, and then I can just pass in a null for Baz, and it -seems- to work.

j-krieger 6y ago

Rust and rustdoc (forget what it‘s called) have the same issues, sadly.

Rotten194 6y ago
rustdoc has the ability to embed usage examples in the doc comments, and automatically test them. also module-level documentation is doable via doc comments in the module main file. rust doesn't force you to write good documentation, but the tools are all there and I often see great documentation for rust crates that was generated with cargo doc. For example the Rocket docs are full of code examples on both the module and function level: https://api.rocket.rs https://api.rocket.rs I think there's something to be said for javadoc, cargo doc, etc encouraging documentation to hew closely to the structure of the code as opposed to a free-form documentation system that can include multiple pages about tasks, getting started, etc. But the vast majority of projects don't bother to set that up, and the javadoc approach makes it very low friction to add docs to existing code that probably already has comments explaining how to use it.
- sidlls 6y ago
  That’s the barebones minimum, because in those contexts the examples are going to be relatively trivial. Often I find them to be no more helpful than the signature doc itself.
  - teknopaul 6y ago
    Even trivial examples that actually compile are better than none. because rust uses real code and markdown reading code and docs is the same thing in many cases, no need to even render to html, absolutely minimal markup noise. I love rust docs. Speaking from many years of using mostly poorly maintained javadocs and well maintained man pages.

freeone3000 6y ago

https://docs.oracle.com/javase/8/docs/api/java/time/Clock.html https://docs.oracle.com/javase/8/docs/api/java/time/Clock.ht... is a bit more involved than the autogenerated template. The Oracle documentation tends towards this level -- the javadoc template is simply where the docs are kept.