Skip to content

docs: api root, buildinfo, csp - #5493

Merged
mtojek merged 31 commits into
coder:mainfrom
mtojek:3522-document-more-methods-2
Dec 22, 2022
Merged

mtojek merged 31 commits into
coder:mainfrom
mtojek:3522-document-more-methods-2

Conversation

@mtojek

@mtojek mtojek commented Dec 21, 2022 •

Copy link
Copy Markdown
Member

Related: #3522

Changes:

  • docs: API root handler, buildinfo, csp
  • fix: updatecheck security
  • fix: code tags on paremeters and enums

@mtojek mtojek self-assigned this Dec 21, 2022
@mtojek
mtojek marked this pull request as ready for review December 21, 2022 15:43
@mtojek
mtojek requested review from bpmct and mafredri December 21, 2022 15:43
@mtojek mtojek changed the title docs: TBD docs: api root, buildinfo, csp Dec 21, 2022
Comment thread coderd/apidoc/docs.go Resolved
Comment thread coderd/apidoc/docs.go Resolved

@mafredri mafredri left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spotted a few minor things, but looks good in general.

One thing I'd like to note though is that it'd be nice if we kept Go comments optimized for humans instead of computers/code-gen. I think we can find ways to automatically process the comments into pretty API documentation.

Comment thread codersdk/updatecheck.go Outdated

// UpdateCheck returns information about the latest release version of
// Coder and whether or not the server is running the latest release.
// UpdateCheck returns information about the latest release version of Coder and whether or not the server is running the latest release.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These comments are somewhat easier to read when there are line-breaks, why do we need to make them a single line (same for the other changes)? (I personally write mine with <=80 char width but we don't enforce it, sub-80 is most prominent in the project though.)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I admit that I changed the line length as I stick to <=120 or <=160 chars (widescreen). I believe that times with <=80 chars are already gone :)

As we fixed the bug with <br>, I guess that we can bring the original multi-line comment back.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

😅. For me it's not about the space, I just find long lines harder to read because my eye needs to travel more sideways.

I also admit I like it when comments align closely to the thing they describe 😆 (like this):
image

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In theory, we could involve one more formatter, golines, to enforce a specific line length limit, but maybe let's leave it aside from this PR.

Comment thread coderd/csp.go Resolved
Comment thread docs/api/schemas.md Resolved
Comment thread docs/api/templates.md Resolved
Comment thread docs/api/templates.md Resolved
Comment thread coderd/coderd.go Resolved
@mtojek
mtojek requested a review from mafredri December 22, 2022 10:03

@mafredri mafredri left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! 👍

@mtojek
mtojek merged commit cfd02d9 into coder:main Dec 22, 2022
@github-actions github-actions Bot locked and limited conversation to collaborators Dec 22, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants