[RFC] Additional metadata for readme examples?

[Adam Faur]

Might be helpful to link out to the code in readme examples.
Links would use a tag or sha to avoid taking the user to the latest changes.

• Update: This might introduce a lot of maintenance though, and I am not sure about it.

server.router.get(String, RouteHandler<ServerRequest, Toolkit>)

// Javascript Example
server.router.get('/', (request, { file }) => {
    return file('./foo.jpg');
});

// Typescript Example
server.router.get('/', (request : ServerRequest, { file } : Toolkit) => {
    return file('./foo.jpg');
});

[Seth Holladay]

Definitely would be useful, but a maintenance burden, as you said.

I think a more "cost effective" approach with roughly similar goals would be:

1. Improve our deno doc output and mention it in various places. Currently, deno doc https://deno.land/x/pogo/main.ts doesn't output anything. To fix this, I believe we need to export our classes as named exports and add doc comments to them.
2. Maybe re-export the types from lib/types.ts in main.ts to make them easier to discover and access?
3. Figure out why GitHub's link-to-definition feature isn't working for us. In most repositories, you can click on code within the README and it will show you its definition and references. It seems to work for most languages, including other Deno projects, but not here. Maybe because the source code is in .ts files but I've used js for the code fences in the docs? Perhaps the languages have to exactly match for GitHub to do its magic.

[Adam Faur]

Opened (#45) to work on items 1 and 2.
Will take a look at 3 soon.

[Seth Holladay]

Looks like my theory about 3 was correct. I did a little experiment in PR #48 and changed a few of the code fences in the documentation to use "ts" instead of "js". Now the code in those examples is clickable, presumably because it matches the language of the source code.

For example, this one:
https://github.com/sholladay/pogo/tree/001d8099157d3a54b542712c2371aab1d768c595#using-hdirectory-recommended

[Seth Holladay]

I added TSDoc comments to further improve the deno doc output in commit 8fa9c0c. I also updated the language of the code examples in the documentation to enable GitHub's link-to-definition feature in commit 4d24945.

With your PR, plus those changes, I think we can probably close this issue. What do you think?

I'm open to any other suggestions for improving the documentation. The next logical step I can think of would be to have a website for the docs.

[Adam Faur]

The only other thing I can think of that may be good to add is a badge in the README.md.

[Seth Holladay]

Thanks, good idea!

Done: fef521c

[Seth Holladay]

Pogo v0.5.0 has been published with these changes. Great work, @afaur!