API reference improvements

[qwwdfsad]

API reference improvements

[dkhalanskyjb]

If applicable, provide details about conversion rules, gotchas and recommendations. Example

I don't know of gotchas related to Instant. The only one that comes to mind is that instant + 1.days is a non-calendar operation (this could be worth documenting in the plus function), but I'd argue it's Duration's gotcha. Instant seems tough to use incorrectly to me. What gotchas did you have in mind?

Where appropriate, information about conversions and interactions with native types (e.g. Instant <-> Java Instant conversion)

When you have specific behavior on some platforms, you document it in the common code, makes sense; but when you have some extra interactions with platform code, you can't document them in common code (because symbols aren't resolved). If you have platform-specific documentation, in the IDE, it is either ignored (when writing common code) or replaces the common documentation. In the latter case, you have to repeat the common documentation for platforms and include platform-specific additions, which I think just isn't worth it.

If the system was a bit different and platform-specific documentation was added to the common documentation (and maybe the IDE would be smart enough to show the documentation for the platforms the project actually uses), then I agree that mentioning platform-specific converters and so on would be beneficial. Or better yet, if there was "extension documentation" along with extension functions: then we'd be able to show NSDate conversions in the Instant documentation for Darwin targets.