Skip to content

Conversation

@itsmath
Copy link
Contributor

@itsmath itsmath commented Mar 7, 2025

This PR introduces a feature that hides comment lines inside ```luau code blocks when they are prefixed by a dollar sign ($).

Initially, I considered # for this purpose since it has been used for this in other languages, like Rust. But I opted for $ because:

  1. # is valid Luau syntax in certain cases:

    local a =
    #b

    While this is rare, it could lead to unintended behavior.

  2. $ currently has no use in Luau and is unlikely to be used in the future, especially if RFC: Reserve the dollar sign token to be forever unused luau-lang/rfcs#44 is accepted.

The lines will only be hidden if they are inside ```luau code blocks. This means you can still have a PHP code block, for example, and it'll work fine.

$this_wont_be_hidden = "because it isn't in ```luau";

If you need to start a line with $, you can use a regular ``` code block, which is still interpreted as a Luau code block by editors, but does not have this behavior.

Use Case

If you're implementing a documentation testing tool, or really any tool that needs to inspect the Luau code inside comments, this feature is very useful.

--- Adds `a` and `b`.
---
--- # Example
---
--- ```luau
--- $ local utils = require("@utils")
--- assert(utils.add(77, 33) == 110, "77 + 33 must be equal to 110")
--- ```
function utils.add(a: number, b: number): number
    return a + b
end

I probably should've started with a GitHub issue first to see if this is even something we want to do, but I was already writing this implementation for my own use, so might as well send a PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant