docs: comment syntax godoc-compatible

[jabielecki]

The godoc and pkg.go.dev do not use Markdown and do not understand asterix nor backtick. With this change it renders correctly.

Adding a badge to the README, so that it would be easy to get the dev's docs when visiting GitHub with just a browser.

[JAORMX]

@jabielecki could you sign your commit using gitsign?

After installing it, you could follow the instructions to enable it for this repository:

cd /path/to/this/repository
git config --local commit.gpgsign true  # Sign all commits
git config --local tag.gpgsign true  # Sign all tags
git config --local gpg.x509.program gitsign  # Use gitsign for signing
git config --local gpg.format x509  # gitsign expects x509 args

[jabielecki]

could you sign your commit using gitsign?

Hmm. My commit previously had a perfectly valid SSH-based signature and was green Verified on Github. It was red on Chainguard Enforce job for some reason.

When I changed to gitsign signature and force-pushed here, it become Unverified on Github ("The signing certificate or its chain could not be verified."). Nothing changed for Chainguard Enforce job, still red. The signature was:

$ git show --show-signature
commit d8e6a2f874bc2f2dcff20a00e06b9a4f7532f26c (HEAD -> jab/godoc1)
tlog index: 4555028
gitsign: Signature made using certificate ID 0xc881749ab78417841bb0a5db6698bf99634718cc | CN=sigstore-intermediate,O=sigstore.dev
gitsign: Good signature from [jakub.bielecki@codilime.com]
Validated Git signature: true
Validated Rekor entry: true
Author: Jakub Bielecki <47531708+jabielecki@users.noreply.github.com>
Date:   Thu Oct 6 09:26:30 2022 +0200

Then I've decided to author with the same email (which was cumbersome operation, but in the end doable). The new signature changed nothing. Unverified on Github ("The signing certificate or its chain could not be verified."). Nothing changed for Chainguard Enforce job, still red. The signature is now:

$ git show --show-signature
commit 1b3bfbca8f28d974af45258a8cb463f184739a48 (HEAD -> jab/godoc1)
tlog index: 4555150
gitsign: Signature made using certificate ID 0xb37b5902cbabcf206138213ebaa4d4e370f29264 | CN=sigstore-intermediate,O=sigstore.dev
gitsign: Good signature from [jakub.bielecki@codilime.com]
Validated Git signature: true
Validated Rekor entry: true
Author: Jakub Bielecki <jakub.bielecki@codilime.com>
Date:   Thu Oct 6 09:26:30 2022 +0200

[JAORMX]

@jabielecki it's actually OK if it's Unverified in GitHub, as long as your commit is verified in the public sigstore transparency log, we can work with this and verify it. GitHub still has work to do to accept sigstore's transparency log... not sure when they'll get this fixed.

[JAORMX]

@jabielecki so... I managed to mess up the chainguard enforce configuration. Here's the fix: #55

However, after pulling your PR, I can verify that it's you 😄 :

$ git verify-commit HEAD
tlog index: 4555150
gitsign: Signature made using certificate ID 0xb37b5902cbabcf206138213ebaa4d4e370f29264 | CN=sigstore-intermediate,O=sigstore.dev
gitsign: Good signature from [jakub.bielecki@codilime.com]
Validated Git signature: true
Validated Rekor entry: true

[codecov-commenter]

Codecov Report

Merging #54 (1b3bfbc) into main (333021c) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main      #54   +/-   ##
=======================================
  Coverage   73.81%   73.81%           
=======================================
  Files          10       10           
  Lines         550      550           
=======================================
  Hits          406      406           
  Misses        115      115           
  Partials       29       29           

Flag	Coverage Δ
unittests	73.81% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
ginjwt/helpers.go	79.01% <ø> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[jabielecki]

@JAORMX Thank you, sir.

The effect of this PR will become visible after next semver tag, e.g. v0.3.1, because pkg.go.dev does not normally use main branch.