Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added the missing xml comments to code & enabled 1591 #230

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/Humanizer/Bytes/ByteSize.cs
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ namespace Humanizer.Bytes
/// <summary>
/// Represents a byte size value.
/// </summary>
#pragma warning disable 1591
public struct ByteSize : IComparable<ByteSize>, IEquatable<ByteSize>
{
public static readonly ByteSize MinValue = FromBits(long.MinValue);
Expand Down Expand Up @@ -384,3 +385,4 @@ public static ByteSize Parse(string s)
}
}
}
#pragma warning restore 1591
3 changes: 3 additions & 0 deletions src/Humanizer/EnumHumanizeExtensions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,9 @@

namespace Humanizer
{
/// <summary>
/// Contains extension methods for humanizing Enums
/// </summary>
public static class EnumHumanizeExtensions
{
private static readonly Func<PropertyInfo, bool> DescriptionProperty = p => p.Name == "Description" && p.PropertyType == typeof (string);
Expand Down
6 changes: 3 additions & 3 deletions src/Humanizer/Humanizer.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<DocumentationFile>bin\Debug\Humanizer.xml</DocumentationFile>
<NoWarn>1591</NoWarn>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure you want this in debug builds? It could get annoying.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we want to enforce it on the PR, then we may as well have it everywhere. Why would this be annoying?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, say you're making/changing some classes as an experiment or 'spike'. Each time you compile, try to run tests, etc, you would be forced to put comments everywhere.

I imagine people end up putting fake comments in, just to get rid of the error, so they can compile and test our their theories.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point; but then again most people code in debug mode. So if we take this out then we're back to square one with PRs missing comments and failing on that! What do you think?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've sent a PR to do what I'm suggesting here - a separate build configuration to verify everything (rather than slow down the normal 'debug' local dev building).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool. Thanks a lot.

</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugType>pdbonly</DebugType>
Expand All @@ -37,7 +37,7 @@
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<DocumentationFile>bin\Release\Humanizer.xml</DocumentationFile>
<NoWarn>1591</NoWarn>
<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'ReleaseNET35|AnyCPU'">
<OutputPath>bin\Release\</OutputPath>
Expand Down Expand Up @@ -204,4 +204,4 @@
<Target Name="AfterBuild">
</Target>
-->
</Project>
</Project>
43 changes: 39 additions & 4 deletions src/Humanizer/Localisation/Formatters/DefaultFormatter.cs
Original file line number Diff line number Diff line change
Expand Up @@ -6,28 +6,41 @@
public class DefaultFormatter : IFormatter
{
/// <summary>
/// Now!
/// Now
/// </summary>
/// <returns>Time expressed in words</returns>
/// <returns>Returns Now</returns>
public virtual string DateHumanize_Now()
{
return GetResourceForDate(TimeUnit.Millisecond, Tense.Past, 0);
}

/// <summary>
/// Returns the string representation of the provided DateTime
/// </summary>
/// <param name="timeUnit"></param>
/// <param name="timeUnitTense"></param>
/// <param name="unit"></param>
/// <returns></returns>
public virtual string DateHumanize(TimeUnit timeUnit, Tense timeUnitTense, int unit)
{
return GetResourceForDate(timeUnit, timeUnitTense, unit);
}

/// <summary>
/// In NO time!
/// 0 seconds
/// </summary>
/// <returns>Time expressed in words</returns>
/// <returns>Returns 0 seconds as the string representation of Zero TimeSpan</returns>
public virtual string TimeSpanHumanize_Zero()
{
return GetResourceForTimeSpan(TimeUnit.Millisecond, 0);
}

/// <summary>
/// Returns the string representation of the provided TimeSpan
/// </summary>
/// <param name="timeUnit"></param>
/// <param name="unit"></param>
/// <returns></returns>
public virtual string TimeSpanHumanize(TimeUnit timeUnit, int unit)
{
return GetResourceForTimeSpan(timeUnit, unit);
Expand All @@ -45,21 +58,43 @@ private string GetResourceForTimeSpan(TimeUnit unit, int count)
return count == 1 ? Format(resourceKey) : Format(resourceKey, count);
}

/// <summary>
///
/// </summary>
/// <param name="resourceKey"></param>
/// <returns></returns>
protected virtual string Format(string resourceKey)
{
return Resources.GetResource(GetResourceKey(resourceKey));
}

/// <summary>
///
/// </summary>
/// <param name="resourceKey"></param>
/// <param name="number"></param>
/// <returns></returns>
protected virtual string Format(string resourceKey, int number)
{
return Resources.GetResource(GetResourceKey(resourceKey, number)).FormatWith(number);
}

/// <summary>
/// Override this method if your locale has complex rules around multiple units; e.g. Arabic, Russian
/// </summary>
/// <param name="resourceKey">The resource key that's being in formatting</param>
/// <param name="number">The number of the units being used in formatting</param>
/// <returns></returns>
protected virtual string GetResourceKey(string resourceKey, int number)
{
return resourceKey;
}

/// <summary>
///
/// </summary>
/// <param name="resourceKey"></param>
/// <returns></returns>
protected virtual string GetResourceKey(string resourceKey)
{
return resourceKey;
Expand Down
25 changes: 24 additions & 1 deletion src/Humanizer/Localisation/Formatters/IFormatter.cs
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,33 @@
/// </summary>
public interface IFormatter
{
/// <summary>
/// Now
/// </summary>
/// <returns>Returns Now</returns>
string DateHumanize_Now();

/// <summary>
/// Returns the string representation of the provided DateTime
/// </summary>
/// <param name="timeUnit"></param>
/// <param name="timeUnitTense"></param>
/// <param name="unit"></param>
/// <returns></returns>
string DateHumanize(TimeUnit timeUnit, Tense timeUnitTense, int unit);


/// <summary>
/// 0 seconds
/// </summary>
/// <returns>Returns 0 seconds as the string representation of Zero TimeSpan</returns>
string TimeSpanHumanize_Zero();

/// <summary>
/// Returns the string representation of the provided TimeSpan
/// </summary>
/// <param name="timeUnit"></param>
/// <param name="unit"></param>
/// <returns></returns>
string TimeSpanHumanize(TimeUnit timeUnit, int unit);
}
}
3 changes: 3 additions & 0 deletions src/Humanizer/Localisation/ResourceKeys.Common.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

namespace Humanizer.Localisation
{
/// <summary>
///
/// </summary>
public partial class ResourceKeys
{
private const string Single = "Single";
Expand Down
3 changes: 3 additions & 0 deletions src/Humanizer/Localisation/ResourceKeys.DateHumanize.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
{
public partial class ResourceKeys
{
/// <summary>
/// Encapsulates the logic required to get the resource keys for DateTime.Humanize
/// </summary>
public static class DateHumanize
{
/// <summary>
Expand Down
3 changes: 3 additions & 0 deletions src/Humanizer/Localisation/ResourceKeys.TimeSpanHumanize.cs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@
{
public partial class ResourceKeys
{
/// <summary>
/// Encapsulates the logic required to get the resource keys for TimeSpan.Humanize
/// </summary>
public static class TimeSpanHumanize
{
/// <summary>
Expand Down
2 changes: 2 additions & 0 deletions src/Humanizer/Localisation/TimeUnit.cs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
/// <summary>
/// Units of time.
/// </summary>
#pragma warning disable 1591
public enum TimeUnit
{
Millisecond,
Expand All @@ -14,4 +15,5 @@ public enum TimeUnit
Month,
Year
}
#pragma warning restore 1591
}
2 changes: 2 additions & 0 deletions src/Humanizer/NoMatchFoundException.cs
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ namespace Humanizer
/// <summary>
/// This is thrown on String.DehumanizeTo enum when the provided string cannot be mapped to the target enum
/// </summary>
#pragma warning disable 1591
public class NoMatchFoundException : Exception
{
public NoMatchFoundException()
Expand All @@ -21,4 +22,5 @@ public NoMatchFoundException(string message, Exception inner)
{
}
}
#pragma warning restore 1591
}
3 changes: 3 additions & 0 deletions src/Humanizer/RomanNumeralExtensions.cs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@

namespace Humanizer
{
/// <summary>
/// Contains extension methods for changing a number to Roman representation (ToRoman) and from Roman representation back to the number (FromRoman)
/// </summary>
public static class RomanNumeralExtensions
{
private const int NumberOfRomanNumeralMaps = 13;
Expand Down
24 changes: 24 additions & 0 deletions src/Humanizer/Transformer/To.cs
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,12 @@ public static string Transform(this string input, params IStringTransformer[] tr
return transformers.Aggregate(input, (current, stringTransformer) => stringTransformer.Transform(current));
}

/// <summary>
/// Changes string to title case
/// </summary>
/// <example>
/// "INvalid caSEs arE corrected" -> "Invalid Cases Are Corrected"
/// </example>
public static IStringTransformer TitleCase
{
get
Expand All @@ -26,6 +32,12 @@ public static IStringTransformer TitleCase
}
}

/// <summary>
/// Changes the string to lower case
/// </summary>
/// <example>
/// "Sentence casing" -> "sentence casing"
/// </example>
public static IStringTransformer LowerCase
{
get
Expand All @@ -34,6 +46,12 @@ public static IStringTransformer LowerCase
}
}

/// <summary>
/// Changes the string to upper case
/// </summary>
/// <example>
/// "lower case statement" -> "LOWER CASE STATEMENT"
/// </example>
public static IStringTransformer UpperCase
{
get
Expand All @@ -42,6 +60,12 @@ public static IStringTransformer UpperCase
}
}

/// <summary>
/// Changes the string to sentence case
/// </summary>
/// <example>
/// "lower case statement" -> "Lower case statement"
/// </example>
public static IStringTransformer SentenceCase
{
get
Expand Down