Documentation Injection by Reference examples are hard to follow

[fatuhoku]

As a relative newcomer, reading this wiki section about Injection by Reference, I read it and still have little idea of how injection by reference works, mainly because the examples are so arbitrary.

For instance, for the following code snippet:

    - (Knight *)knight
    {
        return [TyphoonDefinition withClass:[Knight class] configuration:^(TyphoonDefinition *definition) {
            [definition injectProperty:@selector(quest) with:[self defaultQuest]];
        }];
    }

    - (Knight *)knightWithQuestFromAnotherModule
    {
        return [TyphoonDefinition withClass:[Knight class] configuration:^(TyphoonDefinition *definition) {
            [definition injectProperty:@selector(quest) with:[_questModule scaryQuest]];
        }];
    }

There huge questions in my mind

• "What on earth is [self defaultQuest]? Where did it come from?" — after some digging I found it's actually defined from the first page... this assumes the user must read all the documentation examples in order to make any sense of the examples
• "Well, if I'm supposed to define [self defaultQuest] myself, could I do:

- (Quest *)defaultQuest {
    return [Quest new];
}

...?" — there's no indication that defaultQuest needs to return a TyphoonDefinition. In fact, what actually happens if the user does this?

• "What on earth is _questModule?" — I could have guessed that [self defaultQuest] is supposed to be a Quest, or a TyphoonDefinition that tells us how a Quest object should be set up. But whoa, what's a Module (see Documentation refers to 'Modules' but there's no such concept in Typhoon code #299)? I was completely lost at this point. In hindsight, of course _questModule is simply yet another TyphoonAssembly. Can we stop calling Assemblies 'Modules' already?

[jasperblues]

@fatuhoku Wow, that was pretty messed up. Thanks for reporting.

• Fixed the example so that it shows both the object with dependency (knight), along with the dependency to be injected (quest).
• Removed the example showing injecting something from another assembly, but left the 'see also' link. Folks can read about it there.

[jasperblues]

@fatuhoku Added a note on first page that each assembly method returns a TyphoonDefinition

[jasperblues]

@fatuhoku Ready for review, we can continue on this ticket or raise new issues.

[fatuhoku]

Hiya, the new wiki pages have certainly addressed the concerns I had raised so 🍻 Cheers. =]

[jasperblues]

Cheers. We appreciate your help. Do you see other areas that remain unclear?

Sent from my iPhone

On Dec 24, 2014, at 5:14 AM, Hok Shun Poon notifications@github.com wrote:

Hiya, the new wiki pages have certainly addressed the concerns I had raised so Cheers. =]

—
Reply to this email directly or view it on GitHub.