[RFC] Additional metadata for readme examples?

[afaur]

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');
});

[sholladay]

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.

[afaur]

Opened (https://github.com/sholladay/pogo/pull/45) to work on items 1 and 2. Will take a look at 3 soon.

[sholladay]

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

[sholladay]

I added TSDoc comments to further improve the deno doc output in commit https://github.com/sholladay/pogo/commit/8fa9c0c77be12cffc8a52cc8f51ad50c13366ab4. I also updated the language of the code examples in the documentation to enable GitHub's link-to-definition feature in commit https://github.com/sholladay/pogo/commit/4d24945730f5c4892bed90103be625e6189dd5d3.

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.

[afaur]

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

[sholladay]

Thanks, good idea!

Done: https://github.com/sholladay/pogo/commit/fef521c0b065bb5da627d4e40780a0187312b441

[sholladay]

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