New user - accolades and questions

[adev]

New to swift - this forum is great. Anything that can serve as an alternate to stack overflow is a good thing. Seems positive in a way I'm not used to online. Makes me want to switch my Rails server over to Perfect and my Angular over to... whatever there is. :) Already switched our multiplatform over to dedicated mainly because of this site.

Questions:

1. Is this site actually developed in swift? If so where is the swift client side development? I realize Perfect is on the server side
2. Documentation
   a. Am I missing a section here to discuss documentation? As a new user of swift, there's a lot of 'gotchas'... not because the language is difficult, but the language appears to be something else. For instance, the documentation for Hashable doesn't really correlate to a new user experience, at least mine.
   b. Ever think of creating 'contexts' around documentation - level of experience? Coming from a different language?

I sort of feel like there needs to be a bit more bridging between the Swift Gods and the commoners like me. I'd be glad to help drive that effort if there is an interest in terms of the community.

Thanks, great work.

[John_McCall]

These forums are just a fairly standard instance of Discourse. Discourse (the company) handles the hosting, so I don't think anyone here can tell you much about the stack. The main swift.org site is implemented quite differently, and I think there are some people who know more details about that, although I'm not one of them.

As far I know, nothing about the site is written in Swift, at least not yet.

I think the right place to discuss documentation in general is the Using Swift category. If you have a specific complaint you can also file a bug (the right component for Hashable is Standard Library) or even open a pull request against e.g. the file defining Hashable.

I think most of us would agree about the need for different levels of documentation focusing on different audiences, and any suggestions you have would be valuable. We definitely want there to be a better way to get started using the standard library than just reading all the library docs.

[benrimmington]

@adev

For instance, the documentation for Hashable doesn't really correlate to a new user experience, at least mine.

In addition to the documentation for Equatable and Hashable, there's also an article on Adopting Common Protocols and a video on What's New in Swift.

You might find the following topics useful:

Why does Hashable require Equatable?

Hashable extends Equatable because hashing is a meaningless operation without equality: the requirements on hash values are defined in terms of equal and non-equal elements. From a practical viewpoint, without Equatable, you may be able to add elements to a Dictionary or a Set, but you wouldn't be able to look them up later. This eliminates the primary purpose of these data structures. When you calculate a hash, you're distilling the original value to a fixed-width sequence of bits that can be…

Xcode 10 GM: hash(into:) issue from NSObject class

Cocoa defines its own hashing API that is independent of Swift's Hashable. To customize hashing in NSObject subclasses, the correct property to override is NSObject.hash. Trying to customize hashing by overriding hash(into:) and/or hashValue will not work correctly -- if you do that then NSDictionary, NSSet, and Foundation's other hashing collections won't work correctly with your class, often leading to severe problems. It's rather unfortunate that hash and hashValue have distinct names; the…

How is synthesized Hashable implemented?

The hash function in Swift 4.2 is SipHash-1-3; however, this is an implementation detail that is subject to change in any release. (Note that hashing changed considerably between Swift 4.1 and 4.2. I'm going to concentrate on Swift 4.2 here. Swift 4.1 uses a less robust algorithm to generate hash values, but compiler synthesis works in a roughly similar way.) The new Hasher API (introduced by SE-0206, implemented in 4.2) exposes the standard hash function as public API. It has been carefully de…

Use `Hashable.hash(into:)` or `Hasher.combine(_:)`?

Hasher's generic combine method is defined in Hasher.swift to simply call hash(into:) on its argument: @inlinable @inline(__always) public mutating func combine<H: Hashable>(_ value: H) { value.hash(into: &self) } So hasher.combine(foo) is in fact just an alternative spelling for foo.hash(into: &hasher). They are completely equivalent. Choosing one or the other is a matter of aesthetic preference. I personally prefer to use the generic combine, because it reads clearer to me. (I f…

[gwendal.roue (Gwendal Roué)]

@John_McCall

We definitely want there to be a better way to get started using the standard library than just reading all the library docs.

There are some good examples of well-written Swift documentation. For example, Encoding and Decoding Custom Types is a page I never hesitate linking to. I can even refer to specific paragraphs, because they are well-focused on pragmatic use cases. This really helps answering questions.

[adev]

Very helpful comments from all, thank you. After I feel a little more up to speed on the subtleties of the language and the discussion, I'll send a proposal. My experience is mostly in translating FPGA software models to silicon hardware (kind of like a generic hardware compiler as opposed to mapping to a specific hardware) so we had to consider a lot of contexts depending on usage - data center, machine learning, transceivers, etc. Those designs used multiple documents to capture different levels of abstraction, a section within the document contained a lot of links to other relevant sections in other documents, and different family members repeated information rather than inherited it or extended it.

Honestly I'd probably use POP as the foundation/background for a proposed documentation structure. I don't know enough about POP to really implement fully - but the structures match what I've been looking for in my designs.

As a sidenote, swift would make a great language to verify semiconductors with. The current semiconductor language and libraries are limited.