// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

#pragma warning disable CS1574 // XML comment has cref attribute that could not be resolved

using System.Xml.Linq;
using Microsoft.CodeAnalysis.CSharp.CodeStyle;

namespace Microsoft.CodeAnalysis.CodeStyle;

/// <summary>
/// Defines the known values for <see cref="CSharpCodeStyleOptions.PreferBraces"/>.
/// </summary>
internal enum PreferBracesPreference
{
    /// <summary>
    /// Braces are allowed, but not preferred.
    /// </summary>
    /// <remarks>
    /// <para>The value <c>0</c> is important for serialization compatibility in
    /// <see cref="CodeStyleOption2{T}.FromXElement(XElement)"/>. Prior to the use of this enum, the serialized value
    /// was the <see cref="bool"/> value <see langword="false"/>.</para>
    /// </remarks>
    None = 0,

    /// <summary>
    /// <para>Braces are preferred where allowed except in the following limited situations:</para>
    ///
    /// <list type="bullet">
    /// <item><description>Braces are not required for the embedded statement of an <c>else</c> clause when the embedded statement is an <c>if</c> statement.</description></item>
    /// <item><description>In a sequence of consecutive <c>using</c> statements, only the last statement requires braces.</description></item>
    /// <item><description>In a sequence of consecutive <c>lock</c> statements, only the last statement requires braces.</description></item>
    /// <item><description>In a sequence of consecutive <c>fixed</c> statements, only the last statement requires braces.</description></item>
    /// </list>
    /// </summary>
    /// <remarks>
    /// <para>The value <c>1</c> is important for serialization compatibility in
    /// <see cref="CodeStyleOption2{T}.FromXElement(XElement)"/>. Prior to the use of this enum, the serialized value
    /// was the <see cref="bool"/> value <see langword="true"/>.</para>
    /// </remarks>
    Always = 1,

    /// <summary>
    /// <para>Braces are always allowed, and generally preferred except in limited situations involving single-line
    /// statements and expressions:</para>
    ///
    /// <list type="bullet">
    /// <item><description>Braces may be omitted in the cases described for <see cref="Always"/>.</description></item>
    /// <item><description>Braces may be omitted when the entire statement is placed on one line.</description></item>
    /// <item><description>For a statement that contains one or more embedded statements, braces may be omitted when
    /// every embedded statement fits on one line, and the part preceding the embedded statement is placed on one
    /// line. If any embedded statement uses braces, braces are preferred for all embedded statements of the same
    /// parent statement. For the purposes of evaluating this rule, if the embedded statement following an
    /// <c>else</c> keyword is an if statement, the embedded statements of the nested if statement are treated as
    /// children of the parent statement of the <c>else</c> keyword.</description></item>
    /// </list>
    /// </summary>
    WhenMultiline,
}