search

crystal-lang / crystal-book

Crystal reference with language specification, manuals and learning materials
https://crystal-lang.org/reference
Other
395 stars 248 forks source link

Add `scripts/validate-flags.sh` #734

Closed straight-shoota closed 8 months ago

straight-shoota commented 9 months ago

This script extracts all flag? macro values from the source code and compares them with the documentation. It lists all flags that are currently defined but undocumented.

It depends on crystal tool flags, proposed in https://github.com/crystal-lang/crystal/pull/14234

This could be automated in CI to check flag documentation regularly. Adds a CI workflow that regularly checks flag documentation coverage.

netlify[bot] commented 9 months ago

Deploy Preview for crystal-book ready!

Name Link
Latest commit 2a26e0a4a44d1e60af1a142f05f43386e05dc8f7
Latest deploy log https://app.netlify.com/sites/crystal-book/deploys/65c35d0e02b5580009a2eadc
Deploy Preview https://deploy-preview-734--crystal-book.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

straight-shoota commented 9 months ago

As @Blacksmoke16 observed in https://github.com/crystal-lang/crystal-book/pull/735#issuecomment-1891038352, this script did miss out on flags that are handled by the compiler directly.

I added that now. It's not a fancy compiler tool that investigates the AST. But crystal tool flags is useful for any Crystal program, whereas Program#has_flag? is only relevant for the compiler. So a crude grep implementation does the job as well. There's less variation because the method only accepts String. And we control all the code.