There are no concise lists of all Luau comment directives

Johnnyfireball123 · August 1, 2024, 1:52pm

Currently there is no official documentation on the Luau comment directives (--!nolint --!native) on the Roblox docs. These are very useful features that many developers may never learn about . the CLOSEST I could find to documentation of these was on the luau website, but its missing --!nolint because its in a specific section for typechecking.

Documentation on these would make the quality-of-life of newer users to Luau on Roblox much better. If someone wanted to use --!nolint their code they would first need to learn about the comment directive externally then check the linting section of the Luau website to know what command they need to use (mind you that Studio doesn’t have the same linting that Luau describes such as LocalUnused).

--!native, for example, is mentioned nowhere on the Roblox docs.

Judgy_Oreo · August 1, 2024, 3:48pm

I did a little bit of investigation, and for anyone who wants to know, Luau supports the following directives (or “hot comments”, as it occasionally flip-flops between):

--!nolint - Disables “linting”, warnings that may indicate mistakes but can be ignored
--!nocheck - Disables the typechecker
--!nonstrict - Makes the typechecker more lax towards potential type errors
--!strict - Makes the typechecker “strict” toward potential type errors
--!optimize [X] - An Optimization Controller, 0, 1 or 2 as X (I wouldn’t expect this to be functional on Roblox)
--!native - Native code generation

github.com

luau-lang/luau/blob/58f8c24ddb6c509bd570cd7d3232b9f006c175a5/Analysis/src/Linter.cpp#L2909


      
              }
          }
          else if (first == "native")
          {
              if (space != std::string::npos)
                  emitWarning(
                      context, LintWarning::Code_CommentDirective, hc.location, "native directive has extra symbols at the end of the line");
          }
          else
          {
              static const char* kHotComments[] = {
                  "nolint",
                  "nocheck",
                  "nonstrict",
                  "strict",
                  "optimize",
                  "native",
              };
          
          
    if (const char* suggestion = fuzzyMatch(first, kHotComments, std::size(kHotComments)))
                  emitWarning(context, LintWarning::Code_CommentDirective, hc.location, "Unknown comment directive '%.*s'; did you mean '%s'?",

index_self · August 1, 2024, 4:58pm

It does (at least in studio). It defaults to 1 in playtesting, 2 in live games, and 0 if the file uses any optimization-breaking API (i.e., getfenv and setfenv).

Here’s also a list of all lints you can use for --!nolint. is for disabled in studio, and is for superseded by strict mode.

⛔️	UnknownGlobal
	DeprecatedGlobal
	GlobalUsedAsLocal
❌	LocalShadow
❌	SameLineStatement
	MultiLineStatement
❌	LocalUnused
❌	FunctionUnused
❌	ImportUnused
	BuiltinGlobalWrite
	PlaceholderRead
	UnreachableCode
	UnknownType
	ForRange
	UnbalancedAssignment
⛔️	ImplicitReturn
	DuplicateLocal
	FormatString
	TableLiteral
	UninitializedLocal
	DuplicateFunction
	DeprecatedApi
	TableOperations
	DuplicateCondition
	MisleadingAndOr
	CommentDirective
	IntegerParsing
	ComparisonPrecedence
	RedundantNativeAttribute

Judgy_Oreo · August 1, 2024, 5:11pm

More as in “We can’t override it” rather than it not existing, but thanks for clarifying.

Johnnyfireball123 · August 1, 2024, 5:13pm

Thank you all for digging through Luau source code to help record all of the necessary information in this thread. I think the level of effort it takes to find this information speaks for itself for why proper documentation is needed.

And just to add some insult to injury. Not even the Roblox AI assistant knows what it’s doing (this was after effectively cyber-waterboarding it to tell me more about this until it started making up information)