docs(toh): add return types

[Foxandxss]

So this PR adds return types for ToH. Since we print the code on the screen (as snippets in our guide), it is nice to have those return types on the signature so the readers can see what a method returns.

[Foxandxss]

@wardbell so I like the end result, perhaps the ": void" ones are a bit verbose tho.

In one case, we show an empty method, so I had to put it with : void and then when we put the data in it, I swapped that with the real Promise<Hero[]>.

What do you think?

[chalin]

I totally agree with your reasoning: having explicit return types helps readers figure out what is going on. And this brings the code a bit more aligned with the Dart version. I think the : void is appropriate (and not too verbose).

On the other hand, I find we have too many auxiliary "documentation only" source files, so I'd avoid creating toh-4/ts/app/hero.service.2.ts and just use hero.service.1.ts enhanced with an appropriate type annotation.

cc @kwalrath

[chalin]

In follow-up to my last comment, this is the TS equivalent of what I did on the Dart side of the docs:

  /*
  // #docregion getHeroes-stub
  getHeroes(): Hero[] { return []; }
  // #enddocregion getHeroes-stub
  */