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.

Sign up for GitHub

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

Jump to bottom

Improves XML documentation #167

Merged
merged 2 commits into from
Jul 23, 2020
Merged

Improves XML documentation #167

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7938c90
Merge pull request #1 from serilog/dev
rafaelsc Jul 16, 2020
e44e591
Improve XML Docs
rafaelsc Jul 22, 2020
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
54 changes: 54 additions & 0 deletions src/Serilog.Sinks.File/FileLoggerConfigurationExtensions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@

using System;
using System.ComponentModel;
using System.IO;
using System.Text;
using Serilog.Configuration;
using Serilog.Core;
Expand Down Expand Up @@ -238,6 +239,15 @@ public static LoggerConfiguration File(
/// Ignored if <paramref see="rollingInterval"/> is <see cref="RollingInterval.Infinite"/>.
/// The default is to retain files indefinitely.</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <exception cref="ArgumentNullException">When <paramref name="sinkConfiguration"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="outputTemplate"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
public static LoggerConfiguration File(
this LoggerSinkConfiguration sinkConfiguration,
string path,
Expand Down Expand Up @@ -299,6 +309,15 @@ public static LoggerConfiguration File(
/// Ignored if <paramref see="rollingInterval"/> is <see cref="RollingInterval.Infinite"/>.
/// The default is to retain files indefinitely.</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <exception cref="ArgumentNullException">When <paramref name="sinkConfiguration"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="formatter"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
public static LoggerConfiguration File(
this LoggerSinkConfiguration sinkConfiguration,
ITextFormatter formatter,
Expand Down Expand Up @@ -339,6 +358,14 @@ public static LoggerConfiguration File(
/// the default is "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}".</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <remarks>The file will be written using the UTF-8 character set.</remarks>
/// <exception cref="ArgumentNullException">When <paramref name="sinkConfiguration"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
[Obsolete("New code should not be compiled against this obsolete overload"), EditorBrowsable(EditorBrowsableState.Never)]
public static LoggerConfiguration File(
this LoggerAuditSinkConfiguration sinkConfiguration,
Expand Down Expand Up @@ -367,6 +394,15 @@ public static LoggerConfiguration File(
/// to be changed at runtime.</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <remarks>The file will be written using the UTF-8 character set.</remarks>
/// <exception cref="ArgumentNullException">When <paramref name="sinkConfiguration"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="formatter"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
[Obsolete("New code should not be compiled against this obsolete overload"), EditorBrowsable(EditorBrowsableState.Never)]
public static LoggerConfiguration File(
this LoggerAuditSinkConfiguration sinkConfiguration,
Expand All @@ -393,6 +429,15 @@ public static LoggerConfiguration File(
/// <param name="encoding">Character encoding used to write the text file. The default is UTF-8 without BOM.</param>
/// <param name="hooks">Optionally enables hooking into log file lifecycle events.</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <exception cref="ArgumentNullException">When <paramref name="sinkConfiguration"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="outputTemplate"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
public static LoggerConfiguration File(
this LoggerAuditSinkConfiguration sinkConfiguration,
string path,
Expand Down Expand Up @@ -428,6 +473,15 @@ public static LoggerConfiguration File(
/// <param name="encoding">Character encoding used to write the text file. The default is UTF-8 without BOM.</param>
/// <param name="hooks">Optionally enables hooking into log file lifecycle events.</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <exception cref="ArgumentNullException">When <paramref name="sinkConfiguration"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="formatter"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
public static LoggerConfiguration File(
this LoggerAuditSinkConfiguration sinkConfiguration,
ITextFormatter formatter,
Expand Down
9 changes: 9 additions & 0 deletions src/Serilog.Sinks.File/Sinks/File/FileSink.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,15 @@ public sealed class FileSink : IFileSink, IDisposable
/// is false.</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <remarks>This constructor preserves compatibility with early versions of the public API. New code should not depend on this type.</remarks>
/// <exception cref="ArgumentNullException">When <paramref name="textFormatter"/> is <code>null</code></exception>
/// <exception cref="ArgumentException">When <paramref name="fileSizeLimitBytes"/> is <code>null</code> or less than <code>0</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
[Obsolete("This type and constructor will be removed from the public API in a future version; use `WriteTo.File()` instead.")]
public FileSink(string path, ITextFormatter textFormatter, long? fileSizeLimitBytes, Encoding encoding = null, bool buffered = false)
: this(path, textFormatter, fileSizeLimitBytes, encoding, buffered, null)
Expand Down Expand Up @@ -113,6 +121,7 @@ bool IFileSink.EmitOrOverflow(LogEvent logEvent)
/// Emit the provided log event to the sink.
/// </summary>
/// <param name="logEvent">The log event to write.</param>
/// <exception cref="ArgumentNullException">When <paramref name="logEvent"/> is <code>null</code></exception>
public void Emit(LogEvent logEvent)
{
((IFileSink) this).EmitOrOverflow(logEvent);
Expand Down
2 changes: 1 addition & 1 deletion src/Serilog.Sinks.File/Sinks/File/PeriodicFlushToDiskSink.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ public class PeriodicFlushToDiskSink : ILogEventSink, IDisposable
/// </summary>
/// <param name="sink">The sink to wrap.</param>
/// <param name="flushInterval">The interval at which to flush the underlying sink.</param>
/// <exception cref="ArgumentNullException"/>
/// <exception cref="ArgumentNullException">When <paramref name="sink"/> is <code>null</code></exception>
public PeriodicFlushToDiskSink(ILogEventSink sink, TimeSpan flushInterval)
{
_sink = sink ?? throw new ArgumentNullException(nameof(sink));
Expand Down
8 changes: 8 additions & 0 deletions src/Serilog.Sinks.File/Sinks/File/SharedFileSink.AtomicAppend.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,14 @@ public sealed class SharedFileSink : IFileSink, IDisposable
/// will be written in full even if it exceeds the limit.</param>
/// <param name="encoding">Character encoding used to write the text file. The default is UTF-8 without BOM.</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="textFormatter"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
public SharedFileSink(string path, ITextFormatter textFormatter, long? fileSizeLimitBytes, Encoding encoding = null)
{
if (fileSizeLimitBytes.HasValue && fileSizeLimitBytes < 1)
Expand Down Expand Up @@ -141,6 +148,7 @@ bool IFileSink.EmitOrOverflow(LogEvent logEvent)
/// Emit the provided log event to the sink.
/// </summary>
/// <param name="logEvent">The log event to write.</param>
/// <exception cref="ArgumentNullException">When <paramref name="logEvent"/> is <code>null</code></exception>
public void Emit(LogEvent logEvent)
{
((IFileSink)this).EmitOrOverflow(logEvent);
Expand Down
8 changes: 8 additions & 0 deletions src/Serilog.Sinks.File/Sinks/File/SharedFileSink.OSMutex.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,14 @@ public sealed class SharedFileSink : IFileSink, IDisposable
/// <param name="encoding">Character encoding used to write the text file. The default is UTF-8 without BOM.</param>
/// <returns>Configuration object allowing method chaining.</returns>
/// <remarks>The file will be written using the UTF-8 character set.</remarks>
/// <exception cref="ArgumentNullException">When <paramref name="path"/> is <code>null</code></exception>
/// <exception cref="ArgumentNullException">When <paramref name="textFormatter"/> is <code>null</code></exception>
/// <exception cref="IOException"></exception>
/// <exception cref="InvalidOperationException"></exception>
/// <exception cref="NotSupportedException"></exception>
/// <exception cref="PathTooLongException">When <paramref name="path"/> is too long</exception>
/// <exception cref="UnauthorizedAccessException">The caller does not have the required permission to access the <paramref name="path"/></exception>
/// <exception cref="ArgumentException">Invalid <paramref name="path"/></exception>
public SharedFileSink(string path, ITextFormatter textFormatter, long? fileSizeLimitBytes, Encoding encoding = null)
{
if (path == null) throw new ArgumentNullException(nameof(path));
Expand Down Expand Up @@ -104,6 +111,7 @@ bool IFileSink.EmitOrOverflow(LogEvent logEvent)
/// Emit the provided log event to the sink.
/// </summary>
/// <param name="logEvent">The log event to write.</param>
/// <exception cref="ArgumentNullException">When <paramref name="logEvent"/> is <code>null</code></exception>
public void Emit(LogEvent logEvent)
{
((IFileSink)this).EmitOrOverflow(logEvent);
Expand Down