Our great sponsors
-
tag. There are a number of other useful tags for XML comments which are especially valuable if you use tools like DocFX to automatically generate a documentation website with details and examples. /// /// Converts a string into a coordinate object /// /// A string containing a coordinate to convert /// A coordinate equivelant to the string contained in /// A format exception will be thrown if the structure of the string is unexpected /// /// This demonstrates basic usage of the Parse method: /// /// var c = Coordinate.Parse("1,2"); /// /// public Coordinate Parse(string s) Enter fullscreen mode Exit fullscreen mode Putting it all together We started with a simple class: public class Coordinate { public int X { get; set; } public int Y { get; set; } } Enter fullscreen mode Exit fullscreen mode This might be fine for a simple serialization bucket, but once our upgrades are all done, we've got a class worthy of inclusion in a world-class .NET library. Here's the end result (with comments omitted for brevity): [DebuggerDisplay("({X},{Y})")] public readonly struct Coordinate : IEquatable, IFormattable { public Coordinate(int x, int y) => (X, Y) = (x, y); public int X { get; } public int Y { get; } public override bool Equals(object obj) => obj is Coordinate coordinate && Equals(coordinate); public bool Equals(Coordinate other) => (X, Y) == (other.X, other.Y); public override int GetHashCode() => HashCode.Combine(X, Y); public override string ToString() => ToString(null, null); public string ToString(string format, IFormatProvider formatProvider) { return X.ToString(format, formatProvider) + "," + Y.ToString(format, formatProvider); } public void Deconstruct(out int x, out int y) => (x, y) = (X, Y); public static Coordinate Parse(string s) => CoordinateParser.Parse(s); public static bool TryParse(string s, out Coordinate c) => CoordinateParser.TryParse(s, out c); public static explicit operator Vector(Coordinate c) => Vector.FromCoordinate(c); public static bool operator ==(Coordinate left, Coordinate right) => left.Equals(right); public static bool operator !=(Coordinate left, Coordinate right) => !(left == right); public static Coordinate operator +(Coordinate c) => c; // doesn't do anything, but complements minus public static Coordinate operator -(Coordinate c) => new Coordinate(-c.X, -c.Y); public static Coordinate operator ++(Coordinate c) => new Coordinate(c.X+1, c.Y+1); public static Coordinate operator --(Coordinate c) => new Coordinate(c.X-1, c.Y-1); public static Coordinate operator +(Coordinate left, Coordinate right) => new Coordinate(left.X + right.Y, left.X + right.Y); public static Coordinate operator -(Coordinate left, Coordinate right) => new Coordinate(left.X - right.X, left.Y - right.Y); public static Coordinate operator *(Coordinate left, Coordinate right) => new Coordinate(left.X * right.Y, left.X * right.Y); public static Coordinate operator /(Coordinate left, Coordinate right) => new Coordinate(left.X / right.Y, left.X / right.Y); public static Coordinate operator %(Coordinate left, Coordinate right) => new Coordinate(left.X % right.Y, left.X % right.Y); } Enter fullscreen mode Exit fullscreen mode Ultimately, how far down the road you want to go is a judgement call. For some cases, the first version of the type is all that's required and exactly what's needed. But, if you're writing a library or core domain code, it's probably worth breaking out all the stops to make the experience smoother and more predictable for your users.
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
Related posts
- Anybody know if there's a library for the doc engine that MS Docs/Learn uses?
- Is there a simple way to auto-generate a wiki / documentation for project code that pulls from comments or <summary> tags?
- What the latest tool to generate website docs from /// summary comments?
- How to build a solution like docs.microsoft.com
- What Does Microsoft Use to Create their KB Articles?