Add LDoc based (source generated) documentation

[Tieske]

This should make it easier to keep the documentation up to date, since it is inline.

It has 3 commits;

• adding a query method to supplement similar other ones
• implementing LDoc based documentation (fixing many bad tags etc. that were already present)
• adding the rendered documentation itself

Creating it as a draft PR first for review, and discussion. Check out the branch and point your browser to ./docs/index.html to see the results.

[Tieske]

@EvandroLG I rebase after the other 2 PR's were merged. If you like the idea, then this is essentially good to go. Marking it as ready for review.

[Tieske]

ping @EvandroLG

[Copilot]

Pull request overview

This PR introduces LDoc-based, source-generated documentation for Pegasus, adds a Request:query() convenience API, and checks in the rendered HTML documentation output under docs/.

Changes:

• Add Request:query() as a convenience wrapper around request.querystring.
• Revise/standardize LDoc annotations across core modules and plugins.
• Add LDoc configuration (config.ld) and commit generated documentation artifacts (docs/).

Reviewed changes

Copilot reviewed 38 out of 38 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/pegasus/response.lua	Updates/standardizes response LDoc annotations and clarifies behavior notes (streaming/HEAD).
src/pegasus/request.lua	Adds Request:query() and updates request LDoc annotations/examples.
src/pegasus/plugins/tls.lua	Improves TLS plugin LDoc annotations/types.
src/pegasus/plugins/router.lua	Reworks router plugin docs and example formatting for LDoc output.
src/pegasus/plugins/files.lua	Updates Files plugin docs and LDoc type references.
src/pegasus/plugins/downloads.lua	Updates Downloads plugin docs and LDoc type references.
src/pegasus/plugins/compress.lua	Updates Compress plugin docs (options/constants), leaving implementation unchanged.
src/pegasus/log.lua	Adds module-level LDoc annotation for logging module.
src/pegasus/init.lua	Updates Pegasus entrypoint docs and parameter annotations.
src/pegasus/handler.lua	Updates handler lifecycle docs and LDoc annotations.
config.ld	Adds LDoc configuration for generating documentation into docs/.
docs/index.html	Generated LDoc site index.
docs/ldoc.css	Generated LDoc stylesheet asset.
doc_topics/ldoc.css	Source stylesheet used as LDoc theme input.
docs/topics/README.md.html	Generated HTML for README topic.
docs/topics/LICENSE.html	Generated HTML for LICENSE topic.
docs/topics/01-introduction.md.html	Generated HTML for introduction topic.
docs/topics/02-advanced.md.html	Generated HTML for advanced topic.
docs/examples/app.lua.html	Generated HTML for example app.lua.
docs/examples/app_stream.lua.html	Generated HTML for example app_stream.lua.
docs/examples/copas.lua.html	Generated HTML for example copas.lua.
docs/examples/querystring.lua.html	Generated HTML for example querystring.lua.
docs/examples/write.lua.html	Generated HTML for example write.lua.
docs/classes/pegasus.html	Generated class docs for Pegasus.
docs/classes/pegasus.handler.html	Generated class docs for handler.
docs/classes/pegasus.request.html	Generated class docs for request.
docs/classes/pegasus.response.html	Generated class docs for response.
docs/classes/pegasus.plugins.compress.html	Generated class docs for compress plugin.
docs/classes/pegasus.plugins.downloads.html	Generated class docs for downloads plugin.
docs/classes/pegasus.plugins.files.html	Generated class docs for files plugin.
docs/classes/pegasus.plugins.router.html	Generated class docs for router plugin.
docs/classes/pegasus.plugins.tls.html	Generated class docs for TLS plugin.
docs/modules/logging.html	Generated module docs for logging.
docs/modules/pegasus.response.html	Generated module page present in rendered output.
docs/modules/pegasus.plugins.compress.html	Generated module page present in rendered output.
docs/modules/pegasus.plugins.downloads.html	Generated module page present in rendered output.
docs/modules/pegasus.plugins.files.html	Generated module page present in rendered output.
docs/modules/pegasus.plugins.tls.html	Generated module page present in rendered output.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Because LDoc does not remove files from the output directory, committing a docs/ directory without first cleaning it can leave stale pages around (e.g., old module pages that no longer match the current source annotations). Consider documenting/enforcing a clean step (delete docs/ before running LDoc) or adding a build target/script so the checked-in rendered docs are always in sync.

[Tieske]

this should become part of the release routine I think, or can possibly be added to a makefile, minor imho.

[EvandroLG]

Hey @Tieske! Thanks for the contribution, and sorry for just checking it now - I've been pretty busy with work and personal life lately.

The doc generated is really ugly, right? Not sure if I'd like to go with that, to be honest. Would be nice to at least customize it. WDYT?

Also, from what I see, all the comments from Copilot makes sense.

[Tieske]

Hey @Tieske! Thanks for the contribution, and sorry for just checking it now - I've been pretty busy with work and personal life lately.

no worries.

The doc generated is really ugly, right?

couldn't agree more. But my CSS skills are pretty much non-existent. I use LDoc a lot, because it allows me to keep the docs and code in-sync. This is one of the main issues with current Pegasus repo; docs are badly outdated.
Maybe as a follow-up we can update the design? (I'd be interested to have something better looking that I can reuse in my other repositories as well)

Also, from what I see, all the comments from Copilot makes sense.

Fixed or raised in separate issues.

[Tieske]

I'll rewrite the commits to clean up.

[Tieske]

updated the css to try and improve the looks somewhat, but not very good at it 😞 .