Format markdown comments in modules.caddyhttp.App

[sword-jin]

Format these comments.

[CLAassistant]

All committers have signed the CLA.

[francislavoie]

We're formatting it so it works here:

https://caddyserver.com/docs/json/apps/http/#docs

There's a risk that it might break those docs, so we'll need to check on that before merging this.

[sword-jin]

We're formatting it so it works here:

https://caddyserver.com/docs/json/apps/http/#docs

There's a risk that it might break those docs, so we'll need to check on that before merging this.

Thank you, maybe we need to fix it if it's not compatible, I think some parts of developers are used to read docs on godoc.

[francislavoie]

Yeah definitely, I agree. Just want to make sure it looks right for both, if possible. But we prioritize our docs first.

[mholt]

Woah. Why does that help? I'm not sure I understand 😇

[sword-jin]

By the way, how to compile https://github.com/caddyserver/moduledoc, I didn't find any docs about it. I want to compile on my local environment so I can check it's comparable with our doc system

[mholt]

Huh. When I wrote my review none of the other comments showed up for me (on my phone). I really need to stop trusting the GitHub mobile app.

Yeah, the priority is that it renders properly as markdown on our site.

In order to test the JSON docs locally though you need a DB and a portal repo which isn't currently published. So now that I've seen the other comments, I'll clarify that I haven't verified that yet myself.

What does the godoc look like after this change?

My fear is that this change will cause these docs to go into a big code block instead of being interpreted as markdown.

[sword-jin]

Like that
@mholt

[mholt]

Thanks, that does look a lot better on godocs; it also confirms my suspicions that I think it will cause the docs on our Caddy website to look like that -- one big code block with literal markdown in it. I don't know a way to make it look nice in both places. We might have to choose.

I think most people are reading the docs for templates on our website (which renders Markdown). What's your use case for reading it on the godoc instead of on our website?

[sword-jin]

@mholt
I am used to go though all the API and types on the go doc before I jump into the code. I think maybe other developers have same habit like me,

[mholt]

That's interesting.

I wish we could make both look good, but unfortunately I don't know a way to do that.

I think our first priority needs to make sure that our official docs on our website are legible, especially given that the table shown there isn't intended for Go programmers as much as Caddy users, which likely won't be in the godoc, I'm afraid.

Thanks for the thoughtful change, I just wish we could find a way that wouldn't break our current docs!

Closing, but if a viable solution can be found, we can reopen.