Update parameter and property metadata logic and docs

- Consider IsRetval flag for method return parameters.
- Refine read-only detection: adjust attribute/modifier checks and order.
- Expand isMarkedReadOnly to include optional IsReadOnlyAttribute modifiers.
- Clarify XML docs for IsReadOnly and IsInit in PropertyData.

Author: BionicCode

src/BionicCode.Utilities.Reflection/ParameterData.cs

@@ -197,7 +197,7 @@ internal ParameterData(SymbolReflectionInfoCacheKeyInternal symbolInfoDataCacheK
     /// </summary>
     internal bool IsByRef => _isByRef ??= ParameterTypeData.Type.IsByRef;
 
-    internal bool IsMethodReturnParameter => _isMethodReturnParameter ??= Position == -1;
+    internal bool IsMethodReturnParameter => _isMethodReturnParameter ??= Position < 0 || ParameterInfo.IsRetval;
 
     internal bool IsIndexerPropertyParameter => _isIndexerPropertyParameter ??= MemberData is MethodData methodData && (methodData.IsIndexerPropertyGetMethod || methodData.IsIndexerPropertySetMethod);
 
@@ -321,8 +321,8 @@ private static bool IsRefReadOnlyInternal(ParameterData parameterData)
 
         if (parameterData.IsMethodReturnParameter)
         {
-            return parameterData.HasRequiredCustomModifier(ReflectionConstants.InAttributeFullName)
-                || parameterData.HasCompilerAttribute<IsReadOnlyAttribute>(ReflectionConstants.IsReadOnlyAttributeFullName)
+            return parameterData.HasCompilerAttribute<IsReadOnlyAttribute>(ReflectionConstants.IsReadOnlyAttributeFullName)
+                ||parameterData.HasRequiredCustomModifier(ReflectionConstants.InAttributeFullName)
                 || parameterData.HasRequiredCustomModifier(ReflectionConstants.IsReadOnlyAttributeFullName);
         }
         else
@@ -347,7 +347,9 @@ private static bool IsInParameter(ParameterData parameterData)
         }
 
         // C# 'in' → IsReadOnlyAttribute, but not ref readonly
-        bool isMarkedReadOnly = parameterData.HasCompilerAttribute<IsReadOnlyAttribute>(ReflectionConstants.IsReadOnlyAttributeFullName)
+        bool isMarkedReadOnly = (parameterData.HasCompilerAttribute<IsReadOnlyAttribute>(ReflectionConstants.IsReadOnlyAttributeFullName)
+            || parameterData.HasRequiredCustomModifier(ReflectionConstants.IsReadOnlyAttributeFullName)
+            || parameterData.HasOptionalCustomModifier(ReflectionConstants.IsReadOnlyAttributeFullName))
             && !IsRefReadOnlyInternal(parameterData);
 
         return isMarkedReadOnly;

src/BionicCode.Utilities.Reflection/PropertyData.cs

@@ -914,15 +914,15 @@ internal AccessModifier GetAccessorAccessModifier
     /// <summary>
     /// Gets a value indicating whether the current property has a setter or not.
     /// </summary>
-    /// <remarks>A read-only instance cannot be modified. Use this property to determine if changes to the
-    /// instance are permitted.</remarks>
+    /// <remarks>The <see cref="IsReadOnly"/> property is an alias for the inverted <see cref="CanWrite"/>:
+    /// <br/><c>IsReadOnly == !CanWrite</c></remarks>
     /// <value><see langword="true"/> if the property does not have a setter and is therefore read-only; otherwise, <see langword="false"/>.</value>
     internal bool IsReadOnly => !CanWrite;
 
     /// <summary>
     /// Returns whether the property is an init-only property.
     /// </summary>
-    /// <remarks>This is determined by checking if the property has a setter method and if that setter method is marked with the <see cref="IsExternalInit"/> attribute, 
+    /// <remarks>This is determined by checking if the property has a setter method and if that setter method is marked with the <see cref="IsExternalInit"/> modifier, 
     /// which is used by the C# compiler to indicate init-only properties. 
     /// If the property does not have a setter or if the setter is not marked as init-only, this property returns <see langword="false"/>.</remarks>
     /// <value><see langword="true"/> if the property is an init-only property; otherwise, <see langword="false"/>.</value>