Skip to content

Commit ee1d2ac

Browse files
AragasAragas
authored
Documentation (#8)
* Update appveyor.yml https://github.com/docascode/docfx-seed/blob/master/appveyor.yml * Update appveyor.yml * Update appveyor.yml * Create docfx.json Added default * Update appveyor.yml Whoops * Create toc.yml * Update toc.yml * Update toc.yml * Update toc.yml * moved docfx to docfx folder added some needed(?) files * Update toc.yml * Create toc.yml * Update docfx.json * reverted docfx folder * Update toc.yml * Testing docs in real situation * typo and better handling of src * Better and faster doc generating * Update appveyor.yml * Update appveyor.yml * Added title and favicon * Added logo * Update docfx.json * Update logo.svg * Update logo.svg No idea what I'm doing * Update logo.svg Still no idea * Update logo.svg * Create json-example.md * Update toc.yml * Update toc.yml * Create log-example * Rename log-example to log-example.md * Update toc.yml * Update getting_started.md * Update README.md * Delete PCLExt.FileStorage.sln.DotSettings
1 parent 074c0cb commit ee1d2ac

File tree

17 files changed

+703
-3
lines changed

17 files changed

+703
-3
lines changed

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,3 +194,4 @@ FakesAssemblies/
194194

195195
# Visual Studio 6 workspace options file
196196
*.opt
197+
/docs/_site/*

‎PCLExt.FileStorage.sln.DotSettings‎

Lines changed: 0 additions & 2 deletions
This file was deleted.

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,6 @@ It was formely a basic fork of [PCL Storage](https://github.com/dsplaisted/PCLSt
1111

1212
PCLExt.FileStorage supports .NET Framework (4.5), .NET Standard (2.0), Xamarin.iOS, Xamarin.Android, Xamarin.Mac and UWP.
1313
This makes it easier to create cross-platform .NET libraries and apps.
14+
15+
# Documentation
16+
Examples and API documentation can be found [here](http://pclext.github.io/PCLExt.FileStorage/).

‎appveyor.yml‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,18 +6,51 @@ configuration:
66
platform: Any CPU
77

88
environment:
9-
COVERALLS_REPO_TOKEN:
9+
COVERALLS_REPO_TOKEN:
1010
secure: 7poiWT8gLPZOdo8fwSWeerKD+flRokWUY3Ke5s4TW9+vejCzcH8AXY4pwurPxb9D
11+
op_build_user: "OpenPublishBuild"
12+
op_build_user_email: "[email protected]"
13+
access_token:
14+
secure: GQ3IuQcROfrBh1zCm97nDduFgUcaK9uD4xbawJx5iKcx5IvP7dEahe16nmwF+fQE
1115

1216
install:
1317
- git submodule update --init --recursive
1418

1519
before_build:
1620
- nuget restore
21+
- ps: |
22+
if(-Not $env:APPVEYOR_PULL_REQUEST_TITLE)
23+
{
24+
git checkout $env:APPVEYOR_REPO_BRANCH -q
25+
choco install docfx -y
26+
# choco install nuget.commandline -y
27+
}
1728
1829
build:
1930
project: PCLExt.FileStorage.sln
2031
verbosity: minimal
32+
33+
after_build:
34+
- ps: |
35+
if(-Not $env:APPVEYOR_PULL_REQUEST_TITLE)
36+
{
37+
CD docs
38+
& docfx docfx.json
39+
if ($lastexitcode -ne 0){
40+
throw [System.Exception] "docfx build failed with exit code $lastexitcode."
41+
}
42+
43+
git config --global credential.helper store
44+
Add-Content "$env:USERPROFILE\.git-credentials" "https://$($env:access_token):[email protected]`n"
45+
git config --global user.email $env:op_build_user_email
46+
git config --global user.name $env:op_build_user
47+
git clone https://github.com/PCLExt/PCLExt.FileStorage.git -b gh-pages origin_site -q
48+
Copy-Item origin_site/.git _site -recurse
49+
CD _site
50+
git add -A 2>&1
51+
git commit -m "CI Updates" -q
52+
git push origin gh-pages -q
53+
}
2154
2255
after_test:
2356
- choco install codecov

‎docs/api/.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
###############
2+
# temp file #
3+
###############
4+
*.yml

‎docs/api/.manifest‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
{
2+
"PCLExt.FileStorage": "PCLExt.FileStorage.yml",
3+
"PCLExt.FileStorage.Exceptions": "PCLExt.FileStorage.Exceptions.yml",
4+
"PCLExt.FileStorage.Exceptions.FileExistException": "PCLExt.FileStorage.Exceptions.FileExistException.yml",
5+
"PCLExt.FileStorage.Exceptions.FileExistException.#ctor(System.String)": "PCLExt.FileStorage.Exceptions.FileExistException.yml",
6+
"PCLExt.FileStorage.Exceptions.FileExistException.#ctor(System.String,System.Exception)": "PCLExt.FileStorage.Exceptions.FileExistException.yml",
7+
"PCLExt.FileStorage.Exceptions.FileNotFoundException": "PCLExt.FileStorage.Exceptions.FileNotFoundException.yml",
8+
"PCLExt.FileStorage.Exceptions.FileNotFoundException.#ctor(System.String)": "PCLExt.FileStorage.Exceptions.FileNotFoundException.yml",
9+
"PCLExt.FileStorage.Exceptions.FileNotFoundException.#ctor(System.String,System.Exception)": "PCLExt.FileStorage.Exceptions.FileNotFoundException.yml",
10+
"PCLExt.FileStorage.Exceptions.FolderExistException": "PCLExt.FileStorage.Exceptions.FolderExistException.yml",
11+
"PCLExt.FileStorage.Exceptions.FolderExistException.#ctor(System.String)": "PCLExt.FileStorage.Exceptions.FolderExistException.yml",
12+
"PCLExt.FileStorage.Exceptions.FolderExistException.#ctor(System.String,System.Exception)": "PCLExt.FileStorage.Exceptions.FolderExistException.yml",
13+
"PCLExt.FileStorage.Exceptions.FolderNotFoundException": "PCLExt.FileStorage.Exceptions.FolderNotFoundException.yml",
14+
"PCLExt.FileStorage.Exceptions.FolderNotFoundException.#ctor(System.String)": "PCLExt.FileStorage.Exceptions.FolderNotFoundException.yml",
15+
"PCLExt.FileStorage.Exceptions.FolderNotFoundException.#ctor(System.String,System.Exception)": "PCLExt.FileStorage.Exceptions.FolderNotFoundException.yml",
16+
"PCLExt.FileStorage.Exceptions.RootFolderDeletionException": "PCLExt.FileStorage.Exceptions.RootFolderDeletionException.yml",
17+
"PCLExt.FileStorage.Exceptions.RootFolderDeletionException.#ctor(System.String)": "PCLExt.FileStorage.Exceptions.RootFolderDeletionException.yml",
18+
"PCLExt.FileStorage.Exceptions.RootFolderDeletionException.#ctor(System.String,System.Exception)": "PCLExt.FileStorage.Exceptions.RootFolderDeletionException.yml",
19+
"PCLExt.FileStorage.Extensions": "PCLExt.FileStorage.Extensions.yml",
20+
"PCLExt.FileStorage.Extensions.FileExtensions": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
21+
"PCLExt.FileStorage.Extensions.FileExtensions.AppendLines(IFile,System.Collections.Generic.IEnumerable{System.String})": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
22+
"PCLExt.FileStorage.Extensions.FileExtensions.AppendLinesAsync(IFile,System.Collections.Generic.IEnumerable{System.String})": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
23+
"PCLExt.FileStorage.Extensions.FileExtensions.AppendText(IFile,System.String)": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
24+
"PCLExt.FileStorage.Extensions.FileExtensions.AppendTextAsync(IFile,System.String)": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
25+
"PCLExt.FileStorage.Extensions.FileExtensions.ReadAllLines(IFile)": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
26+
"PCLExt.FileStorage.Extensions.FileExtensions.ReadAllLinesAsync(IFile)": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
27+
"PCLExt.FileStorage.Extensions.FileExtensions.ReadAllText(IFile)": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
28+
"PCLExt.FileStorage.Extensions.FileExtensions.ReadAllTextAsync(IFile)": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
29+
"PCLExt.FileStorage.Extensions.FileExtensions.WriteAllLines(IFile,System.Collections.Generic.IEnumerable{System.String})": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
30+
"PCLExt.FileStorage.Extensions.FileExtensions.WriteAllLinesAsync(IFile,System.Collections.Generic.IEnumerable{System.String})": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
31+
"PCLExt.FileStorage.Extensions.FileExtensions.WriteAllText(IFile,System.String)": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
32+
"PCLExt.FileStorage.Extensions.FileExtensions.WriteAllTextAsync(IFile,System.String)": "PCLExt.FileStorage.Extensions.FileExtensions.yml",
33+
"PCLExt.FileStorage.Extensions.FolderExtensions": "PCLExt.FileStorage.Extensions.FolderExtensions.yml",
34+
"PCLExt.FileStorage.Extensions.FolderExtensions.GetFileFromPath(IFolder,System.String)": "PCLExt.FileStorage.Extensions.FolderExtensions.yml",
35+
"PCLExt.FileStorage.Extensions.FolderExtensions.GetFileFromPath(IFolder,System.String[])": "PCLExt.FileStorage.Extensions.FolderExtensions.yml",
36+
"PCLExt.FileStorage.Extensions.FolderExtensions.GetFolderFromPath(IFolder,System.String)": "PCLExt.FileStorage.Extensions.FolderExtensions.yml",
37+
"PCLExt.FileStorage.Extensions.FolderExtensions.GetFolderFromPath(IFolder,System.String[])": "PCLExt.FileStorage.Extensions.FolderExtensions.yml",
38+
"PCLExt.FileStorage.Files": "PCLExt.FileStorage.Files.yml",
39+
"PCLExt.FileStorage.Files.FileFromPath": "PCLExt.FileStorage.Files.FileFromPath.yml",
40+
"PCLExt.FileStorage.Files.FileFromPath.#ctor(System.String)": "PCLExt.FileStorage.Files.FileFromPath.yml",
41+
"PCLExt.FileStorage.Folders": "PCLExt.FileStorage.Folders.yml",
42+
"PCLExt.FileStorage.Folders.ApplicationRootFolder": "PCLExt.FileStorage.Folders.ApplicationRootFolder.yml",
43+
"PCLExt.FileStorage.Folders.ApplicationRootFolder.#ctor": "PCLExt.FileStorage.Folders.ApplicationRootFolder.yml",
44+
"PCLExt.FileStorage.Folders.DocumentsRootFolder": "PCLExt.FileStorage.Folders.DocumentsRootFolder.yml",
45+
"PCLExt.FileStorage.Folders.DocumentsRootFolder.#ctor": "PCLExt.FileStorage.Folders.DocumentsRootFolder.yml",
46+
"PCLExt.FileStorage.Folders.FolderFromPath": "PCLExt.FileStorage.Folders.FolderFromPath.yml",
47+
"PCLExt.FileStorage.Folders.FolderFromPath.#ctor(System.String)": "PCLExt.FileStorage.Folders.FolderFromPath.yml",
48+
"PCLExt.FileStorage.Folders.LocalRootFolder": "PCLExt.FileStorage.Folders.LocalRootFolder.yml",
49+
"PCLExt.FileStorage.Folders.LocalRootFolder.#ctor": "PCLExt.FileStorage.Folders.LocalRootFolder.yml",
50+
"PCLExt.FileStorage.Folders.RoamingRootFolder": "PCLExt.FileStorage.Folders.RoamingRootFolder.yml",
51+
"PCLExt.FileStorage.Folders.RoamingRootFolder.#ctor": "PCLExt.FileStorage.Folders.RoamingRootFolder.yml",
52+
"PCLExt.FileStorage.Folders.TempRootFolder": "PCLExt.FileStorage.Folders.TempRootFolder.yml",
53+
"PCLExt.FileStorage.Folders.TempRootFolder.#ctor": "PCLExt.FileStorage.Folders.TempRootFolder.yml",
54+
"PCLExt.FileStorage.PortablePath": "PCLExt.FileStorage.PortablePath.yml",
55+
"PCLExt.FileStorage.PortablePath.Combine(System.String[])": "PCLExt.FileStorage.PortablePath.yml",
56+
"PCLExt.FileStorage.PortablePath.DirectorySeparatorChar": "PCLExt.FileStorage.PortablePath.yml",
57+
"PCLExt.FileStorage.PortablePath.GetExtension(System.String)": "PCLExt.FileStorage.PortablePath.yml",
58+
"PCLExt.FileStorage.PortablePath.GetFileName(System.String)": "PCLExt.FileStorage.PortablePath.yml",
59+
"PCLExt.FileStorage.PortablePath.GetFileNameWithoutExtension(System.String)": "PCLExt.FileStorage.PortablePath.yml",
60+
"PCLExt.FileStorage.PortablePath.HasExtension(System.String)": "PCLExt.FileStorage.PortablePath.yml"
61+
}

‎docs/api/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# API Reference
2+
3+
Welcome to PCLExt.FileStorage reference. To begin, select a namespace, then a class, from the table of contents on the left.

‎docs/articles/getting_started.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# APIs
2+
The primary APIs are the IFile and IFolder interfaces. BaseFile and BaseFolder implements them as abstract classes.

‎docs/articles/json-example.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# JSON File
2+
Class that serializes/deserializes JSON file.
3+
4+
```cs
5+
public abstract class JsonFile : BaseFile
6+
{
7+
/// <summary>
8+
/// Ignores readonly properties from BaseFile in the Json file.
9+
/// </summary>
10+
protected class BaseFileResolver : DefaultContractResolver
11+
{
12+
protected override IList<JsonProperty>
13+
CreateProperties(Type type, MemberSerialization memberSerialization) =>
14+
base.CreateProperties(type, memberSerialization)
15+
.Where(p => p.PropertyName != nameof(Name) &&
16+
p.PropertyName != nameof(Path) &&
17+
p.PropertyName != nameof(Exists) &&
18+
p.PropertyName != nameof(Size))
19+
.ToList();
20+
}
21+
22+
protected virtual JsonSerializerSettings GetSettings() => new JsonSerializerSettings()
23+
{
24+
ContractResolver = new BaseFileResolver(),
25+
Formatting = Formatting.Indented
26+
};
27+
28+
protected JsonFile(IFile file) : base(file)
29+
{
30+
Reload();
31+
}
32+
33+
/// <summary>
34+
/// Will trigger Save() if field has changed.
35+
/// </summary>
36+
protected void SetValueIfChangedAndSave<TRet>(ref TRet backingField, TRet newValue)
37+
{
38+
if (!EqualityComparer<TRet>.Default.Equals(backingField, newValue))
39+
{
40+
backingField = newValue;
41+
Save();
42+
}
43+
}
44+
45+
public bool Reload()
46+
{
47+
try
48+
{
49+
var content = this.ReadAllText();
50+
if (string.IsNullOrEmpty(content))
51+
this.WriteAllText(content = JsonConvert.SerializeObject(this, GetSettings()));
52+
53+
JsonConvert.PopulateObject(content, this, GetSettings());
54+
return true;
55+
}
56+
catch (JsonSerializationException) // Json file is invalid, replace with the default valid one.
57+
{
58+
// Comment this to prevent replacing invalid json with default values.
59+
this.WriteAllText(JsonConvert.SerializeObject(this, GetSettings()));
60+
return false;
61+
}
62+
}
63+
public bool Save()
64+
{
65+
try
66+
{
67+
this.WriteAllText(JsonConvert.SerializeObject(this, GetSettings()));
68+
return true;
69+
}
70+
catch (JsonSerializationException)
71+
{
72+
return false;
73+
}
74+
}
75+
76+
protected async Task<bool> ReloadAsync()
77+
{
78+
try
79+
{
80+
var content = await this.ReadAllTextAsync();
81+
if (string.IsNullOrEmpty(content))
82+
await this.WriteAllTextAsync(content = JsonConvert.SerializeObject(this, GetSettings()));
83+
84+
JsonConvert.PopulateObject(content, this, GetSettings());
85+
return true;
86+
}
87+
catch (JsonSerializationException) // Json file is invalid, replace with the default valid one.
88+
{
89+
// Comment this to prevent replacing with default.
90+
await this.WriteAllTextAsync(JsonConvert.SerializeObject(this, GetSettings()));
91+
return false;
92+
}
93+
}
94+
public async Task<bool> SaveAsync()
95+
{
96+
try
97+
{
98+
await this.WriteAllTextAsync(JsonConvert.SerializeObject(this, GetSettings()));
99+
return true;
100+
}
101+
catch (JsonSerializationException)
102+
{
103+
return false;
104+
}
105+
}
106+
}
107+
public class SomeJsonFile : JsonFile
108+
{
109+
private string _serverName = "Put Server Name Here";
110+
public string ServerName { get => _serverName; set => SetValueIfChangedAndSave(ref _serverName, value); }
111+
112+
private string _serverMessage = "Put Server Description Here";
113+
public string ServerMessage { get => _serverMessage; set => SetValueIfChangedAndSave(ref _serverMessage, value); }
114+
115+
private int _maxPlayers = 1000;
116+
public int MaxPlayers { get => _maxPlayers; set => SetValueIfChangedAndSave(ref _maxPlayers, value); }
117+
118+
119+
public SomeJsonFile() : base(new ApplicationRootFolder().CreateFile("Some.json", CreationCollisionOption.OpenIfExists)) { }
120+
}
121+
122+
public class OtherJsonFile : JsonFile
123+
{
124+
public string ServerName { get; set; } = "Put Server Name Here";
125+
126+
public string ServerMessage { get; set; } = "Put Server Description Here";
127+
128+
public int MaxPlayers { get; set; } = 1000;
129+
130+
131+
public OtherJsonFile() : base(new ApplicationRootFolder().CreateFile("Other.json", CreationCollisionOption.OpenIfExists)) { }
132+
}
133+
```

‎docs/articles/log-example.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+
```

0 commit comments

Comments
 (0)