[fix-finder] Add XML documentation to `Android.Util.Log` convenience overloads

[github-actions]

Problem

The 18 public convenience methods in src/Mono.Android/Android.Util/Log.cs have no XML documentation comments. These format-string and Throwable-accepting overloads of Debug, Error, Info, Verbose, Warn, Wtf, and WriteLine are commonly used by developers and should have <summary>, <param>, and <returns> documentation.

Location

• File: src/Mono.Android/Android.Util/Log.cs
• Lines: 17–110 (all public methods except FormatProvider, which already has docs)

Current Code

All 18 methods follow one of three patterns, none with XML docs:

// Pattern 1: format string overload
public static int Debug (string tag, string format, params object[] args)
{
    return Debug (tag, string.Format (FormatProvider, format, args));
}

// Pattern 2: Throwable + message
public static int Debug (string tag, Java.Lang.Throwable tr, string msg)
{
    return Debug (tag, msg, tr);
}

// Pattern 3: Throwable + format string
public static int Debug (string tag, Java.Lang.Throwable tr, string format, params object[] args)
{
    return Debug (tag, string.Format (FormatProvider, format, args), tr);
}

This same three-pattern structure repeats for Error, Info, Verbose, Warn, Wtf, plus a single format overload for WriteLine.

Suggested Fix

Add /// <summary>, /// <param>, and /// <returns> XML doc comments to each method. Example for the three Debug overloads:

/// <summary>
/// Sends a <see cref="LogPriority.Debug"/> log message using a composite format string.
/// </summary>
/// <param name="tag">Used to identify the source of a log message.</param>
/// <param name="format">A composite format string.</param>
/// <param name="args">An object array that contains zero or more objects to format.</param>
/// <returns>The number of bytes written.</returns>
/// <seealso href="(developer.android.com/redacted),%20java.lang.String)">Android documentation for <c>android.util.Log.d</c></seealso>
public static int Debug (string tag, string format, params object[] args)

/// <summary>
/// Sends a <see cref="LogPriority.Debug"/> log message with an associated <see cref="Java.Lang.Throwable"/>.
/// </summary>
/// <param name="tag">Used to identify the source of a log message.</param>
/// <param name="tr">An exception to log.</param>
/// <param name="msg">The message to log.</param>
/// <returns>The number of bytes written.</returns>
/// <seealso href="(developer.android.com/redacted),%20java.lang.String,%20java.lang.Throwable)">Android documentation for <c>android.util.Log.d</c></seealso>
public static int Debug (string tag, Java.Lang.Throwable tr, string msg)

/// <summary>
/// Sends a <see cref="LogPriority.Debug"/> log message using a composite format string, with an associated <see cref="Java.Lang.Throwable"/>.
/// </summary>
/// <param name="tag">Used to identify the source of a log message.</param>
/// <param name="tr">An exception to log.</param>
/// <param name="format">A composite format string.</param>
/// <param name="args">An object array that contains zero or more objects to format.</param>
/// <returns>The number of bytes written.</returns>
/// <seealso href="(developer.android.com/redacted),%20java.lang.String,%20java.lang.Throwable)">Android documentation for <c>android.util.Log.d</c></seealso>
public static int Debug (string tag, Java.Lang.Throwable tr, string format, params object[] args)

Apply the same pattern to all other log levels, adjusting:

• LogPriority.Debug → LogPriority.Error / LogPriority.Info / LogPriority.Verbose / LogPriority.Warn / LogPriority.Wtf
• The <seealso> Android doc URL letter: d → e / i / v / w / wtf

For WriteLine, use:

/// <summary>
/// Writes a log message at the specified priority using a composite format string.
/// </summary>
/// <param name="priority">The priority of the log message.</param>
/// <param name="tag">Used to identify the source of a log message.</param>
/// <param name="format">A composite format string.</param>
/// <param name="args">An object array that contains zero or more objects to format.</param>
/// <returns>The number of bytes written.</returns>
/// <seealso href="(developer.android.com/redacted),%20java.lang.String,%20java.lang.String)">Android documentation for <c>android.util.Log.println</c></seealso>
public static int WriteLine (LogPriority priority, string tag, string format, params object[] args)

Guidelines

• Use tabs for indentation (repo convention)
• Use <see cref="..."/> for .NET type references
• Use <seealso href="..."> for Android documentation links
• Do not modify any code, only add XML doc comments
• Follow the same doc style as the existing FormatProvider property doc (lines 9–11)

Acceptance Criteria

• All 18 public methods in Log.cs have /// <summary>, /// <param>, and /// <returns> XML documentation
• Each <summary> references the corresponding LogPriority enum value via <see cref="..."/>
• Each method includes a <seealso> link to the relevant Android documentation
• All tests pass
• No new warnings introduced

Fix-finder metadata

• Script: 04-missing-xml-docs
• Score: 28/30 (actionability: 10, safety: 10, scope: 8)

Generated by Nightly Fix Finder · ● 16.5M · ◷

• expires on Jun 19, 2026, 2:31 AM UTC