Document everything, and turn on errors if we fail to document anything in the future.

3 files changed, 30 insertions, 2 deletions

diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs b/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs
index c69d1b23..18ebefd2 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs
@@ -38,7 +38,13 @@ namespace Google.Protobuf.WellKnownTypes
     // providing a conversion to TimeSpan and convenience operators.
     public partial class Duration
     {
+        /// <summary>
+        /// The number of nanoseconds in a second.
+        /// </summary>
         public const int NanosecondsPerSecond = 1000000000;
+        /// <summary>
+        /// The number of nanoseconds in a BCL tick (as used by <see cref="TimeSpan"/> and <see cref="DateTime"/>).
+        /// </summary>
         public const int NanosecondsPerTick = 100;
 
         /// <summary>
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs b/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs
index a3806b5c..dd485d32 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs
@@ -43,16 +43,35 @@ namespace Google.Protobuf.WellKnownTypes
     /// </summary>
     public static class TimeExtensions
     {
+        /// <summary>
+        /// Converts the given <see cref="DateTime"/> to a <see cref="Timestamp"/>.
+        /// </summary>
+        /// <param name="dateTime">The date and time to convert to a timestamp.</param>
+        /// <exception cref="ArgumentException">The <paramref name="dateTime"/> value has a <see cref="DateTime.Kind"/>other than <c>Utc</c>.</exception>
+        /// <returns>The converted timestamp.</returns>
         public static Timestamp ToTimestamp(this DateTime dateTime)
         {
             return Timestamp.FromDateTime(dateTime);
         }
 
+        /// <summary>
+        /// Converts the given <see cref="DateTimeOffset"/> to a <see cref="Timestamp"/>
+        /// </summary>
+        /// <remarks>The offset is taken into consideration when converting the value (so the same instant in time
+        /// is represented) but is not a separate part of the resulting value. In other words, there is no
+        /// roundtrip operation to retrieve the original <c>DateTimeOffset</c>.</remarks>
+        /// <param name="dateTimeOffset">The date and time (with UTC offset) to convert to a timestamp.</param>
+        /// <returns>The converted timestamp.</returns>
         public static Timestamp ToTimestamp(this DateTimeOffset dateTimeOffset)
         {
             return Timestamp.FromDateTimeOffset(dateTimeOffset);
         }
 
+        /// <summary>
+        /// Converts the given <see cref="TimeSpan"/> to a <see cref="Duration"/>.
+        /// </summary>
+        /// <param name="timeSpan">The time span to convert.</param>
+        /// <returns>The converted duration.</returns>
         public static Duration ToDuration(this TimeSpan timeSpan)
         {
             return Duration.FromTimeSpan(timeSpan);
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs b/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs
index 1aa392c7..68584358 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs
@@ -136,9 +136,12 @@ namespace Google.Protobuf.WellKnownTypes
         }
 
         /// <summary>
-        /// Converts the specified <see cref="DateTimeOffset"/> to a <see cref="Timestamp"/>.
+        /// Converts the given <see cref="DateTimeOffset"/> to a <see cref="Timestamp"/>
         /// </summary>
-        /// <param name="dateTime"></param>
+        /// <remarks>The offset is taken into consideration when converting the value (so the same instant in time
+        /// is represented) but is not a separate part of the resulting value. In other words, there is no
+        /// roundtrip operation to retrieve the original <c>DateTimeOffset</c>.</remarks>
+        /// <param name="dateTimeOffset">The date and time (with UTC offset) to convert to a timestamp.</param>
         /// <returns>The converted timestamp.</returns>
         public static Timestamp FromDateTimeOffset(DateTimeOffset dateTimeOffset)
         {