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

Add missing KeyType documentation #2783

Merged
merged 6 commits into from
Mar 12, 2019
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
30 changes: 26 additions & 4 deletions src/Microsoft.ML.Core/Data/KeyType.cs
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,10 @@ namespace Microsoft.ML.Data
/// class numbers, etc. For example, in multi-class classification, the label is typically
/// a class number which is naturally a KeyType.
///
/// KeyTypes have a cardinality (i.e., Count) that is strictly positive.
/// KeyTypes have a cardinality (i.e., <see cref="Count"/>) that is strictly positive.
///
/// Note that the underlying representation value does not necessarily match the logical value.
/// For example, if a KeyType has range 0-5000, then it has a Count of 5001, but
/// For example, if a KeyType has range 0-5000, then it has a <see cref="Count"/> of 5001, but
/// the representational values are 1-5001. The representation value zero is reserved
/// to mean a missing value (similar to NaN).
/// </summary>
Expand Down Expand Up @@ -52,13 +52,20 @@ public static bool IsValidDataType(Type type)

/// <summary>
/// <see cref="Count"/> is the cardinality of the <see cref="KeyType"/>. Note that such a key type can be converted to a
/// bit vector representation by mapping to a vector of length Count, with "id" mapped to a
/// bit vector representation by mapping to a vector of length <see cref="Count"/>, with "id" mapped to a
/// vector with 1 in slot (id - 1) and 0 in all other slots. This is the standard "indicator"
/// representation. Note that an id of 0 is used to represent the notion "none", which is
/// typically mapped, by for example, one-hot encoding, to a vector of all zeros (of length Count).
/// typically mapped, by for example, one-hot encoding, to a vector of all zeros (of length <see cref="Count"/>).
/// </summary>
public ulong Count { get; }

/// <summary>
/// Determine if this <see cref="KeyType"/> object is equal to another <see cref="DataViewType"/> instance.
/// Checks if the other item is the type of <see cref="KeyType"/>, if the <see cref="DataViewType.RawType"/>
/// is the same, and if the <see cref="Count"/> is the same.
/// </summary>
/// <param name="other">The other object to compare against.</param>
/// <returns><see langword="true" /> if both objects are equal, otherwise <see langword="false"/>.</returns>
public override bool Equals(DataViewType other)
{
if (other == this)
Expand All @@ -73,16 +80,31 @@ public override bool Equals(DataViewType other)
return true;
}

/// <summary>
/// Determine if a <see cref="KeyType"/> instance is equal to another <see cref="KeyType"/> instance.
/// Checks if any object is the type of <see cref="KeyType"/>, if the <see cref="DataViewType.RawType"/>
/// is the same, and if the <see cref="Count"/> is the same.
/// </summary>
/// <param name="other">The other object to compare against.</param>
/// <returns><see langword="true" /> if both objects are equal, otherwise <see langword="false"/>.</returns>
public override bool Equals(object other)
{
return other is DataViewType tmp && Equals(tmp);
}

/// <summary>
/// Retrieves the hash code.
/// </summary>
/// <returns>An integer representing the hash code.</returns>
public override int GetHashCode()
{
return Hashing.CombinedHash(RawType.GetHashCode(), Count);
}

/// <summary>
/// The string representation of the <see cref="KeyType"/>.
/// </summary>
/// <returns>A formatted string.</returns>
public override string ToString()
{
InternalDataKind rawKind = this.GetRawKind();
Expand Down