Skip to content

Commit 47659da

Browse files
AragasAragas
committed
Improved documentation
1 parent 939e6d8 commit 47659da

File tree

17 files changed

+86
-51
lines changed

17 files changed

+86
-51
lines changed

‎docs/articles/available.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
You have a `Logs` folder and need to create a log file with the current datetime as it's name, e.g. `2017-06-23.13.45.56.log`
2+
```cs
3+
public class LogsFolder : BaseFolder
4+
{
5+
public LogsFolder() : base(new ApplicationFolder().CreateFolder("Logs", CreationCollisionOption.OpenIfExists)) { }
6+
}
7+
8+
public class LogFile : BaseFile
9+
{
10+
public LogFile() : base(new LogsFolder().CreateFile($"{DateTime.Now:yyyy-MM-dd_HH.mm.ss}.log", CreationCollisionOption.OpenIfExists)) { }
11+
}
12+
13+
...
14+
15+
using(var fs = new LogFile().Open(FileAccess.ReadAndWrite))
16+
{
17+
// -- Do something with the log file
18+
}
19+
```

‎src/PCLExt.FileStorage.Portable111/Exceptions/FileExistException.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
namespace PCLExt.FileStorage.Exceptions
44
{
5-
/// <exclude/>
5+
/// <summary>
6+
/// The exception that is thrown when an attempt to create a file fails because it already exists on disk.
7+
/// </summary>
68
public class FileExistException
79
#if PORTABLE
810
: System.IO.IOException
9-
#elif NETSTANDARD2_0
10-
: System.IO.IOException
1111
#else
1212
: System.IO.IOException
1313
#endif

‎src/PCLExt.FileStorage.Portable111/Exceptions/FileNotFoundException.cs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@
1111

1212
namespace PCLExt.FileStorage.Exceptions
1313
{
14-
/// <exclude/>
14+
/// <summary>
15+
/// The exception that is thrown when an attempt to access a file that does not exist on disk fails.
16+
/// </summary>
1517
public class FileNotFoundException
1618
#if PORTABLE
1719
: System.IO.IOException

‎src/PCLExt.FileStorage.Portable111/Exceptions/FolderExistException.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
namespace PCLExt.FileStorage.Exceptions
44
{
5-
/// <exclude/>
5+
/// <summary>
6+
/// The exception that is thrown when an attempt to create a folder fails because it already exists on disk.
7+
/// </summary>
68
public class FolderExistException
79
#if PORTABLE
810
: System.IO.IOException
9-
#elif NETSTANDARD2_0
10-
: System.IO.IOException
1111
#else
1212
: System.IO.IOException
1313
#endif

‎src/PCLExt.FileStorage.Portable111/Exceptions/FolderNotFoundException.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,12 @@
1111

1212
namespace PCLExt.FileStorage.Exceptions
1313
{
14-
/// <exclude/>
14+
/// <summary>
15+
/// The exception that is thrown when an attempt to access a folder that does not exist on disk fails.
16+
/// </summary>
1517
public class FolderNotFoundException
1618
#if PORTABLE
1719
: System.IO.IOException
18-
#elif NETSTANDARD2_0
19-
: System.IO.FileNotFoundException
2020
#else
2121
: System.IO.DirectoryNotFoundException
2222
#endif

‎src/PCLExt.FileStorage.Portable111/Exceptions/RootFolderDeletionException.cs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22

33
namespace PCLExt.FileStorage.Exceptions
44
{
5-
/// <exclude/>
5+
/// <summary>
6+
/// The exception that is thrown when an attempt to delete a root folder fails.
7+
/// </summary>
68
public class RootFolderDeletionException
79
#if PORTABLE
810
: System.IO.IOException
9-
#elif NETSTANDARD2_0
10-
: System.IO.IOException
1111
#else
1212
: System.IO.IOException
1313
#endif

‎src/PCLExt.FileStorage.Portable111/Extensions/FileExtensions.cs‎

Lines changed: 19 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ public static class FileExtensions
2323
/// Reads the contents of a file as a string
2424
/// </summary>
2525
/// <param name="file">The file to read </param>
26-
/// <returns>The contents of the file</returns>
26+
/// <returns>The content of the file</returns>
2727
public static string ReadAllText(this IFile file)
2828
{
2929
using (var stream = file.Open(FileAccess.Read))
@@ -36,7 +36,7 @@ public static string ReadAllText(this IFile file)
3636
/// </summary>
3737
/// <param name="file">The file to read </param>
3838
/// <param name="cancellationToken">The cancellation token.</param>
39-
/// <returns>The contents of the file</returns>
39+
/// <returns>The content of the file</returns>
4040
public static async Task<string> ReadAllTextAsync(this IFile file, CancellationToken cancellationToken = default(CancellationToken))
4141
{
4242
using (var stream = await file.OpenAsync(FileAccess.Read, cancellationToken).ConfigureAwait(false))
@@ -48,23 +48,22 @@ public static string ReadAllText(this IFile file)
4848
/// Writes text to a file, overwriting any existing data
4949
/// </summary>
5050
/// <param name="file">The file to write to</param>
51-
/// <param name="contents">The content to write to the file</param>
52-
/// <returns>A task which completes when the write operation finishes</returns>
53-
public static void WriteAllText(this IFile file, string contents)
51+
/// <param name="content">The content to write to the file</param>
52+
public static void WriteAllText(this IFile file, string content)
5453
{
5554
using (var stream = file.Open(FileAccess.ReadAndWrite))
5655
{
5756
stream.SetLength(0);
5857
using (var sw = new StreamWriter(stream))
59-
sw.Write(contents);
58+
sw.Write(content);
6059
}
6160
}
6261

6362
/// <summary>
6463
/// Writes text to a file, overwriting any existing data
6564
/// </summary>
6665
/// <param name="file">The file to write to</param>
67-
/// <param name="contents">The content to write to the file</param>
66+
/// <param name="content">The content to write to the file</param>
6867
/// <param name="cancellationToken">The cancellation token.</param>
6968
/// <returns>A task which completes when the write operation finishes</returns>
7069
public static async Task WriteAllTextAsync(this IFile file, string contents, CancellationToken cancellationToken = default(CancellationToken))
@@ -73,16 +72,16 @@ public static void WriteAllText(this IFile file, string contents)
7372
{
7473
stream.SetLength(0);
7574
using (var sw = new StreamWriter(stream))
76-
await sw.WriteAsync(contents).ConfigureAwait(false);
75+
await sw.WriteAsync(content).ConfigureAwait(false);
7776
}
7877
}
7978

8079

8180
/// <summary>
82-
///
81+
/// Reads the contents of a file as an array of strings
8382
/// </summary>
84-
/// <param name="file"></param>
85-
/// <returns></returns>
83+
/// <param name="file">The file to read </param>
84+
/// <returns>The content of the file</returns>
8685
public static string[] ReadAllLines(this IFile file)
8786
{
8887
using (var stream = file.Open(FileAccess.Read))
@@ -96,11 +95,11 @@ public static string[] ReadAllLines(this IFile file)
9695
}
9796

9897
/// <summary>
99-
///
98+
/// Reads the contents of a file as an array of strings
10099
/// </summary>
101-
/// <param name="file"></param>
100+
/// <param name="file">The file to read </param>
102101
/// <param name="cancellationToken">The cancellation token.</param>
103-
/// <returns></returns>
102+
/// <returns>The content of the file</returns>
104103
public static async Task<string[]> ReadAllLinesAsync(this IFile file, CancellationToken cancellationToken = default(CancellationToken))
105104
{
106105
using (var stream = await file.OpenAsync(FileAccess.Read, cancellationToken).ConfigureAwait(false))
@@ -114,10 +113,10 @@ public static string[] ReadAllLines(this IFile file)
114113
}
115114

116115
/// <summary>
117-
///
116+
/// Writes lines to a file, overwriting any existing data
118117
/// </summary>
119-
/// <param name="file"></param>
120-
/// <param name="lines"></param>
118+
/// <param name="file">The file to write to</param>
119+
/// <param name="lines">The content to write to the file</param>
121120
public static void WriteAllLines(this IFile file, IEnumerable<string> lines)
122121
{
123122
using (var stream = file.Open(FileAccess.ReadAndWrite))
@@ -130,10 +129,10 @@ public static void WriteAllLines(this IFile file, IEnumerable<string> lines)
130129
}
131130

132131
/// <summary>
133-
///
132+
/// Writes lines to a file, overwriting any existing data
134133
/// </summary>
135-
/// <param name="file"></param>
136-
/// <param name="lines"></param>
134+
/// <param name="file">The file to write to</param>
135+
/// <param name="lines">The content to write to the file</param>
137136
/// <param name="cancellationToken">The cancellation token.</param>
138137
public static async Task WriteAllLinesAsync(this IFile file, IEnumerable<string> lines, CancellationToken cancellationToken = default(CancellationToken))
139138
{

‎src/PCLExt.FileStorage.Portable111/Files/FileFromPath.cs‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,18 @@
11
namespace PCLExt.FileStorage.Files
22
{
33
/// <summary>
4-
/// Represents a folder created by a given path
4+
/// Represents a a <see cref="BaseFile"/> created by a given path.
55
/// </summary>
66
public class FileFromPath : BaseFile
77
{
88
/// <summary>
9-
/// Creates a new <see cref="IFile"/> corresponding to the specified path.
9+
/// Creates a new <see cref="BaseFile"/> corresponding to the specified path.
10+
/// </summary>
11+
/// <param name="paths">An array of parts of the path.</param>
12+
public FileFromPath(params string[] paths) : base(GetFileFromPath(System.IO.Path.Combine(paths))) { }
13+
14+
/// <summary>
15+
/// Creates a new <see cref="BaseFile"/> corresponding to the specified path.
1016
/// </summary>
1117
/// <param name="path">The file path</param>
1218
public FileFromPath(string path) : base(GetFileFromPath(path)) { }

‎src/PCLExt.FileStorage.Portable111/Folders/ApplicationRootFolder.cs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
namespace PCLExt.FileStorage.Folders
22
{
33
/// <summary>
4-
/// A folder where the app is running.
4+
/// A <see cref="BaseFolder"/> where the application is running.
55
/// </summary>
66
public class ApplicationRootFolder : BaseFolder
77
{
88
/// <summary>
9-
/// Returns the folder where the app is running.
9+
/// Returns the <see cref="BaseFolder"/> where the application is running.
10+
/// Does not exist in Android and UWP
1011
/// </summary>
1112
#if !PORTABLE
1213
public ApplicationRootFolder() : base(GetApplicationFolder()) { }

‎src/PCLExt.FileStorage.Portable111/Folders/DocumentsRootFolder.cs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
namespace PCLExt.FileStorage.Folders
44
{
55
/// <summary>
6-
/// A folder where the app is running.
6+
/// A <see cref="BaseFolder"/> where the app is running.
77
/// </summary>
88
public class DocumentsRootFolder : BaseFolder
99
{
1010
/// <summary>
11-
/// Returns the folder where the app is running.
11+
/// Returns the <see cref="BaseFolder"/> where the app is running.
1212
/// </summary>
1313
#if !PORTABLE
1414
public DocumentsRootFolder() : base(GetDocumentsFolder()) { }

0 commit comments

Comments
 (0)