nicko 2004/12/05 18:21:41
Modified: src/DateFormatter AbsoluteTimeDateFormatter.cs
DateTimeDateFormatter.cs IDateFormatter.cs
Iso8601DateFormatter.cs SimpleDateFormatter.cs
Log:
Updated doc comments
Revision Changes Path
1.6 +24 -13
logging-log4net/src/DateFormatter/AbsoluteTimeDateFormatter.cs
Index: AbsoluteTimeDateFormatter.cs
===================================================================
RCS file:
/home/cvs/logging-log4net/src/DateFormatter/AbsoluteTimeDateFormatter.cs,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- AbsoluteTimeDateFormatter.cs 29 Nov 2004 16:56:16 -0000 1.5
+++ AbsoluteTimeDateFormatter.cs 6 Dec 2004 02:21:41 -0000 1.6
@@ -23,8 +23,13 @@
namespace log4net.DateFormatter
{
/// <summary>
- /// Formats a <see cref="DateTime"/> in the format
<c>"HH:mm:ss,SSS"</c> for example, <c>"15:49:37,459"</c>.
+ /// Formats a <see cref="DateTime"/> as <c>"HH:mm:ss,SSS"</c>.
/// </summary>
+ /// <remarks>
+ /// <para>
+ /// Formats a <see cref="DateTime"/> in the format
<c>"HH:mm:ss,SSS"</c> for example, <c>"15:49:37,459"</c>.
+ /// </para>
+ /// </remarks>
/// <author>Nicko Cadell</author>
/// <author>Gert Driesen</author>
public class AbsoluteTimeDateFormatter : IDateFormatter
@@ -32,16 +37,18 @@
#region Protected Instance Methods
/// <summary>
- /// Renders the date into a string. Format is "HH:mm:ss".
+ /// Renders the date into a string. Format is <c>"HH:mm:ss"</c>.
/// </summary>
+ /// <param name="dateToFormat">The date to render into a
string.</param>
+ /// <param name="buffer">The string builder to write to.</param>
/// <remarks>
- /// Sub classes should override this method to render the date
+ /// <para>
+ /// Subclasses should override this method to render the date
/// into a string using a precision up to the second. This
method
/// will be called at most once per second and the result will
be
/// reused if it is needed again during the same second.
+ /// </para>
/// </remarks>
- /// <param name="dateToFormat">The date to render into a
string.</param>
- /// <param name="buffer">The string builder to write to.</param>
virtual protected void FormatDateWithoutMillis(DateTime
dateToFormat, StringBuilder buffer)
{
int hour = dateToFormat.Hour;
@@ -75,17 +82,21 @@
/// <summary>
/// Renders the date into a string. Format is "HH:mm:ss,SSS".
/// </summary>
+ /// <param name="dateToFormat">The date to render into a
string.</param>
+ /// <param name="writer">The writer to write to.</param>
/// <remarks>
- /// <para>Uses the FormatDateWithoutMillis() method to generate
the
+ /// <para>
+ /// Uses the <see cref="FormatDateWithoutMillis"/> method to
generate the
/// time string up to the seconds and then appends the current
- /// milliseconds. The results from FormatDateWithoutMillis() are
- /// cached and FormatDateWithoutMillis() is called at most once
- /// per second.</para>
- /// <para>Sub classes should override FormatDateWithoutMillis()
- /// rather than FormatDate().</para>
+ /// milliseconds. The results from <see
cref="FormatDateWithoutMillis"/> are
+ /// cached and <see cref="FormatDateWithoutMillis"/> is called
at most once
+ /// per second.
+ /// </para>
+ /// <para>
+ /// Sub classes should override <see
cref="FormatDateWithoutMillis"/>
+ /// rather than <see cref="FormatDate"/>.
+ /// </para>
/// </remarks>
- /// <param name="dateToFormat">The date to render into a
string.</param>
- /// <param name="writer">The writer to write to.</param>
virtual public void FormatDate(DateTime dateToFormat,
TextWriter writer)
{
// Calculate the current time precise only to the second
1.4 +26 -9
logging-log4net/src/DateFormatter/DateTimeDateFormatter.cs
Index: DateTimeDateFormatter.cs
===================================================================
RCS file:
/home/cvs/logging-log4net/src/DateFormatter/DateTimeDateFormatter.cs,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- DateTimeDateFormatter.cs 29 Nov 2004 16:56:16 -0000 1.3
+++ DateTimeDateFormatter.cs 6 Dec 2004 02:21:41 -0000 1.4
@@ -23,8 +23,15 @@
namespace log4net.DateFormatter
{
/// <summary>
- /// Formats a <see cref="DateTime"/> in the format <c>"dd MMM YYYY
HH:mm:ss,SSS"</c> for example, <c>"06 Nov 1994 15:49:37,459"</c>.
+ /// Formats a <see cref="DateTime"/> as <c>"dd MMM YYYY
HH:mm:ss,SSS"</c>
/// </summary>
+ /// <remarks>
+ /// <para>
+ /// Formats a <see cref="DateTime"/> in the format
+ /// <c>"dd MMM YYYY HH:mm:ss,SSS"</c> for example,
+ /// <c>"06 Nov 1994 15:49:37,459"</c>.
+ /// </para>
+ /// </remarks>
/// <author>Nicko Cadell</author>
/// <author>Gert Driesen</author>
/// <author>Angelika Schnagl</author>
@@ -33,8 +40,13 @@
#region Public Instance Constructors
/// <summary>
- /// Initializes a new instance of the <see
cref="DateTimeDateFormatter" /> class.
+ /// Default constructor.
/// </summary>
+ /// <remarks>
+ /// <para>
+ /// Initializes a new instance of the <see
cref="DateTimeDateFormatter" /> class.
+ /// </para>
+ /// </remarks>
public DateTimeDateFormatter()
{
m_dateTimeFormatInfo = DateTimeFormatInfo.InvariantInfo;
@@ -45,15 +57,20 @@
#region Override implementation of AbsoluteTimeDateFormatter
/// <summary>
- /// Formats the date as: "dd MMM YYYY HH:mm:ss"
- /// the base class will append the ',SSS' milliseconds section.
- /// We will only be called at most once per second.
+ /// Formats the date without the milliseconds part
/// </summary>
- /// <remarks>
- /// Formats a DateTime in the format "dd MMM YYYY HH:mm:ss" for
example, "06 Nov 1994 15:49:37".
- /// </remarks>
/// <param name="dateToFormat">The date to format.</param>
/// <param name="buffer">The string builder to write to.</param>
+ /// <remarks>
+ /// <para>
+ /// Formats a DateTime in the format <c>"dd MMM YYYY
HH:mm:ss"</c>
+ /// for example, <c>"06 Nov 1994 15:49:37"</c>.
+ /// </para>
+ /// <para>
+ /// The base class will append the <c>",SSS"</c> milliseconds
section.
+ /// This method will only be called at most once per second.
+ /// </para>
+ /// </remarks>
override protected void FormatDateWithoutMillis(DateTime
dateToFormat, StringBuilder buffer)
{
int day = dateToFormat.Day;
@@ -81,7 +98,7 @@
/// <summary>
/// The format info for the invariant culture.
/// </summary>
- private readonly DateTimeFormatInfo m_dateTimeFormatInfo;
+ private readonly DateTimeFormatInfo m_dateTimeFormatInfo;
#endregion Private Instance Fields
}
1.3 +16 -1 logging-log4net/src/DateFormatter/IDateFormatter.cs
Index: IDateFormatter.cs
===================================================================
RCS file: /home/cvs/logging-log4net/src/DateFormatter/IDateFormatter.cs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- IDateFormatter.cs 16 Feb 2004 02:10:53 -0000 1.2
+++ IDateFormatter.cs 6 Dec 2004 02:21:41 -0000 1.3
@@ -22,9 +22,18 @@
namespace log4net.DateFormatter
{
/// <summary>
+ /// Render a <see cref="DateTime"/> as a string.
+ /// </summary>
+ /// <remarks>
+ /// <para>
/// Interface to abstract the rendering of a <see cref="DateTime"/>
/// instance into a string.
- /// </summary>
+ /// </para>
+ /// <para>
+ /// The <see cref="FormatDate"/> method is used to render the
+ /// date to a text writer.
+ /// </para>
+ /// </remarks>
/// <author>Nicko Cadell</author>
/// <author>Gert Driesen</author>
public interface IDateFormatter
@@ -34,6 +43,12 @@
/// </summary>
/// <param name="dateToFormat">The date to format.</param>
/// <param name="writer">The writer to write to.</param>
+ /// <remarks>
+ /// <para>
+ /// Format the <see cref="DateTime"/> as a string and write it
+ /// to the <see cref="TextWriter"/> provided.
+ /// </para>
+ /// </remarks>
void FormatDate(DateTime dateToFormat, TextWriter writer);
}
}
1.4 +22 -5 logging-log4net/src/DateFormatter/Iso8601DateFormatter.cs
Index: Iso8601DateFormatter.cs
===================================================================
RCS file:
/home/cvs/logging-log4net/src/DateFormatter/Iso8601DateFormatter.cs,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Iso8601DateFormatter.cs 29 Nov 2004 16:56:16 -0000 1.3
+++ Iso8601DateFormatter.cs 6 Dec 2004 02:21:41 -0000 1.4
@@ -22,8 +22,13 @@
namespace log4net.DateFormatter
{
/// <summary>
- /// Formats the <see cref="DateTime"/> specified as a string:
<c>"YYYY-MM-dd HH:mm:ss,SSS"</c>.
+ /// Formats the <see cref="DateTime"/> as <c>"YYYY-MM-dd
HH:mm:ss,SSS"</c>.
/// </summary>
+ /// <remarks>
+ /// <para>
+ /// Formats the <see cref="DateTime"/> specified as a string:
<c>"YYYY-MM-dd HH:mm:ss,SSS"</c>.
+ /// </para>
+ /// </remarks>
/// <author>Nicko Cadell</author>
/// <author>Gert Driesen</author>
public class Iso8601DateFormatter : AbsoluteTimeDateFormatter
@@ -31,8 +36,13 @@
#region Public Instance Constructors
/// <summary>
- /// Initializes a new instance of the <see
cref="Iso8601DateFormatter" /> class.
+ /// Default constructor
/// </summary>
+ /// <remarks>
+ /// <para>
+ /// Initializes a new instance of the <see
cref="Iso8601DateFormatter" /> class.
+ /// </para>
+ /// </remarks>
public Iso8601DateFormatter()
{
}
@@ -42,12 +52,19 @@
#region Override implementation of AbsoluteTimeDateFormatter
/// <summary>
- /// Formats the date specified as a string: 'YYYY-MM-dd
HH:mm:ss'
- /// the base class will append the ',SSS' milliseconds section.
- /// We will only be called at most once per second.
+ /// Formats the date without the milliseconds part
/// </summary>
/// <param name="dateToFormat">The date to format.</param>
/// <param name="buffer">The string builder to write to.</param>
+ /// <remarks>
+ /// <para>
+ /// Formats the date specified as a string: <c>"YYYY-MM-dd
HH:mm:ss"</c>.
+ /// </para>
+ /// <para>
+ /// The base class will append the <c>",SSS"</c> milliseconds
section.
+ /// This method will only be called at most once per second.
+ /// </para>
+ /// </remarks>
override protected void FormatDateWithoutMillis(DateTime
dateToFormat, StringBuilder buffer)
{
buffer.Append(dateToFormat.Year);
1.3 +21 -3 logging-log4net/src/DateFormatter/SimpleDateFormatter.cs
Index: SimpleDateFormatter.cs
===================================================================
RCS file: /home/cvs/logging-log4net/src/DateFormatter/SimpleDateFormatter.cs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- SimpleDateFormatter.cs 16 Feb 2004 02:10:53 -0000 1.2
+++ SimpleDateFormatter.cs 6 Dec 2004 02:21:41 -0000 1.3
@@ -24,6 +24,11 @@
/// <summary>
/// Formats the <see cref="DateTime"/> using the <see
cref="DateTime.ToString"/> method.
/// </summary>
+ /// <remarks>
+ /// <para>
+ /// Formats the <see cref="DateTime"/> using the <see cref="DateTime"/>
<see cref="DateTime.ToString"/> method.
+ /// </para>
+ /// </remarks>
/// <author>Nicko Cadell</author>
/// <author>Gert Driesen</author>
public class SimpleDateFormatter : IDateFormatter
@@ -31,14 +36,19 @@
#region Public Instance Constructors
/// <summary>
- /// Initializes a new instance of the <see
cref="SimpleDateFormatter" /> class
- /// with the specified format string.
+ /// Constructor
/// </summary>
+ /// <param name="format">The format string.</param>
/// <remarks>
+ /// <para>
+ /// Initializes a new instance of the <see
cref="SimpleDateFormatter" /> class
+ /// with the specified format string.
+ /// </para>
+ /// <para>
/// The format string must be compatible with the options
/// that can be supplied to <see cref="DateTime.ToString"/>.
+ /// </para>
/// </remarks>
- /// <param name="format">The format string.</param>
public SimpleDateFormatter(string format)
{
m_formatString = format;
@@ -53,6 +63,12 @@
/// </summary>
/// <param name="dateToFormat">The date to convert to a
string.</param>
/// <param name="writer">The writer to write to.</param>
+ /// <remarks>
+ /// <para>
+ /// Uses the date format string supplied to the constructor to
call
+ /// the <see cref="DateTime.ToString(string)"/> method to
format the date.
+ /// </para>
+ /// </remarks>
virtual public void FormatDate(DateTime dateToFormat,
TextWriter writer)
{
writer.Write(dateToFormat.ToString(m_formatString,
System.Globalization.DateTimeFormatInfo.InvariantInfo));
@@ -66,8 +82,10 @@
/// The format string used to format the <see cref="DateTime"
/>.
/// </summary>
/// <remarks>
+ /// <para>
/// The format string must be compatible with the options
/// that can be supplied to <see cref="DateTime.ToString"/>.
+ /// </para>
/// </remarks>
private readonly string m_formatString;
