Quick: Add footnotes to Documentation for code samples that rely on code not shown

[RShergold]

I'm working through the extremely good documentation and trying to recreate all examples given.

At "better failure messages"
https://github.com/Quick/Quick/blob/master/Documentation/NimbleAssertions.md#better-failure-messages-part-2-nimble-failure-messages

I seem to be getting a much more cryptic failure message than the screen shot

expecting

failed - expected to contain <Monkey(name: Kiki, silliness: ExtremelySilly)>, got <[Monkey(name: Jane, silliness: VerySilly)]>

got

failed - expected to contain <Optional(Testing_With_QuickTests.Monkey)>, got <("Testing_With_QuickTests.Monkey")>

My failing test
https://github.com/RShergold/Testing-With-Quick/blob/5f9759448e9c56c0bdf1998c2c213e5140e68607/Testing%20With%20QuickTests/MonkeySpec.swift#L39

My monkey object
https://github.com/RShergold/Testing-With-Quick/blob/5f9759448e9c56c0bdf1998c2c213e5140e68607/Testing%20With%20Quick/Monkey.swift

I'm on Xcode 6.3 beta with Swift 1.2

Can someone point me in the right direction and maybe make the documentation a little clearer if I've made a very simple mistake.

Thanks guys

[modocache]

@RShergold I think you got me! I remember writing some of the code in the documentation thinking, "Well, this doesn't exactly work, but it gets the point across." So it's more than possible that some of the failures don't 100% match up with what actually happens.

The difference here is that Monkey needs to conform to Printable in order to return a more pleasant description. Something like:

extension Silliness {
    var description: String {
        switch self {
        case .ExtremelySilly: return "ExtremelySilly"
        // ...and so on.
        }
    }
}

extension Monkey {
    var description: String {
        return "Monkey(name: \(name), silliness: \(silliness))"
    }
}

I thought that adding the above code would make the documentation more confusing, but now that I see that you're going through each of the examples, I think I'd like to add footnotes that get the code to work as expected (like Functional Programming in Swift does). I'll use this issue to track making those changes.

Thanks for the heads up! Please file more issues if you have any other input! :+1:

[RShergold]

Thanks for the quick reply. I 100% get the need for the documentation to get straight to the point. I'm enjoying the examples :monkey_face:

[noisypigeon]

Is there anything that needs to be done for this issue?

[modocache]

The concrete next step here would be to run through the examples in the documentation and double-check they all produce the stated output. For the ones that don't, either the examples should be updated, or a footnote should be added. The footnote would state that "OK, well, the output isn't _exactly_ what you see here, but it would take a lot more code to display that exacty output!"

I'm not 100% sure it's worth it to do this, though. Seems like it'd be a lot of work! 😅

[mokagio]

I'd love to help with this.

What about having a "DocumentationExamples" repo, with all the examples?

It would be a lot of work, but also a great place to start for people new with the framework?

[noisypigeon]

I created a repository called https://github.com/quick/wiki which we could use for this, @mokagio. The goal is to introduce a website for documentation as well in the future. If you'd like, you could start to add those examples in a directory called Documentation Examples/ in that repository. When we get to adding a website, we can convert them to markdown or webpages or whatever we choose to use.

[mokagio]

Sounds good :) I'll should be able to look into it within the next two nights.

[noisypigeon]

Sounds good. @modocache; would you be able to add @mokagio to the organisation?

[jeffh]

I've added @mokagio to the org. Welcome! 🎉

[noisypigeon]

Yay! (And thanks to whoever made me an Admin/Owner).

[modocache]

Oops, sorry @istx25! That was my original intention but @jeffh pointed out you weren't one. He corrected my mistake :+1:

[noisypigeon]

No problem! 💃

[noisypigeon]

This issue is being continued in the Wiki repository. I'm going to close this issue for now but feel free to file more issues on that repository or reopen this one if necessary.