Hacker News Reader

Comment by lostcolony | Hacker News Reader

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.

View on HN

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

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.

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

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.

found something! kinda: 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

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.

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.

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.

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

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

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.

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.

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.

Reply on news.ycombinator.com