Support Nullable Reference Type annotations

Author: kalimag

src/BizHawk.Client.Common/lua/Documentation/LuaCatsGenerator.cs

@@ -148,7 +148,7 @@ public static void Generate(LuaDocumentation docs, string path)
 					else
 					{
 						sb.Append($"---@param {parameter.Name}");
-						if (parameter.IsOptional || IsNullable(parameter.ParameterType))
+						if (CanBeNil(parameter))
 						{
 							sb.Append('?');
 						}
@@ -170,7 +170,13 @@ public static void Generate(LuaDocumentation docs, string path)
 				if (func.Method.ReturnType != typeof(void))
 				{
 					sb.Append("---@return ");
-					sb.Append(GetLuaType(func.Method.ReturnParameter));
+					var luaType = GetLuaType(func.Method.ReturnParameter);
+					var nilable = CanBeNil(func.Method.ReturnParameter);
+					var wrapType = nilable && luaType.IndexOfAny([ ':', '|' ]) != -1; // ? is ambiguous on complex types like `string|int` or `fun(): string`
+					if (wrapType) sb.Append('(');
+					sb.Append(luaType);
+					if (wrapType) sb.Append(')');
+					if (nilable) sb.Append('?');
 					if (IsZeroIndexed(func.Method.ReturnParameter))
 					{
 						sb.Append(" # Zero-indexed array.");
@@ -261,7 +267,7 @@ private static string GetLuaType(Type type)
 			return GetLuaType(type.GetElementType()) + "[]";
 		}
 
-		if (IsNullable(type))
+		if (IsNullableValueType(type))
 		{
 			type = type.GetGenericArguments()[0];
 		}
@@ -274,7 +280,48 @@ private static string GetLuaType(Type type)
 		throw new NotSupportedException($"Unknown type {type.FullName} used in API. Generator must be updated to handle this.");
 	}
 
-	private static bool IsNullable(Type type) => type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Nullable<>);
+	private static bool CanBeNil(ParameterInfo parameter) => parameter.HasDefaultValue || IsNullableValueType(parameter.ParameterType) || IsNullableReferenceType(parameter);
+
+	private static bool IsNullableValueType(Type type) => type.IsValueType && type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Nullable<>);
+
+	/// <summary>
+	/// Returns <see langword="true"/> if <paramref name="parameter"/> is a reference type and is annotated as nullable or lacks NRT annotations.
+	/// </summary>
+	/// <remarks>
+	/// Only handles "top-level" types, not array elements or generic type parameters.
+	/// </remarks>
+	private static bool IsNullableReferenceType(ParameterInfo parameter)
+	{
+		if (parameter.ParameterType.IsValueType) return false;
+
+		// https://github.com/dotnet/roslyn/blob/main/docs/features/nullable-metadata.md
+		const byte AnnotatedNotNull = 1;
+
+		// Check [Nullable] on the parameter first
+		if (GetNullableFlags(parameter) is byte[] flags)
+		{
+			return flags[0] != AnnotatedNotNull;
+		}
+
+		// Check [NullableContext] on the method and parent types
+		var parent = parameter.Member;
+		while (parent is not null)
+		{
+			if (GetNullableContext(parent) is byte flag)
+			{
+				return flag != AnnotatedNotNull;
+			}
+			parent = parent.DeclaringType;
+		}
+
+		return true;
+
+		// Attributes may be compiled into each assembly, so can't be strongly typed
+		static byte[]? GetNullableFlags(ParameterInfo parameter) =>
+			((dynamic) parameter.GetCustomAttributes().SingleOrDefault(attr => attr.GetType().FullName == "System.Runtime.CompilerServices.NullableAttribute"))?.NullableFlags;
+		static byte? GetNullableContext(MemberInfo member) =>
+			((dynamic) member.GetCustomAttributes().SingleOrDefault(attr => attr.GetType().FullName == "System.Runtime.CompilerServices.NullableContextAttribute"))?.Flag;
+	}
 
 	private static bool IsParams(ParameterInfo parameter) => parameter.GetCustomAttribute<ParamArrayAttribute>() is not null;