Skip to content

Commit 27fd622

Browse files
vlada-shubinavlada-shubina
committed
documentation in Abstractions
1 parent ffe7a2b commit 27fd622

File tree

21 files changed

+162
-18
lines changed

21 files changed

+162
-18
lines changed

‎src/Microsoft.TemplateEngine.Abstractions/IBaselineInfo.cs

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,26 @@
11
// Licensed to the .NET Foundation under one or more agreements.
22
// The .NET Foundation licenses this file to you under the MIT license.
33

4+
#nullable enable
5+
46
using System.Collections.Generic;
57

68
namespace Microsoft.TemplateEngine.Abstractions
79
{
10+
/// <summary>
11+
/// Defines baseline configuration information.
12+
/// Baseline configuration is a set of predefined template parameters and their values.
13+
/// </summary>
814
public interface IBaselineInfo
915
{
10-
string Description { get; }
16+
/// <summary>
17+
/// Gets baseline description.
18+
/// </summary>
19+
string? Description { get; }
1120

21+
/// <summary>
22+
/// Gets collection of parameters to be set with given baseline.
23+
/// </summary>
1224
IReadOnlyDictionary<string, string> DefaultOverrides { get; }
1325
}
1426
}

‎src/Microsoft.TemplateEngine.Abstractions/IFileChange.cs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33

44
#nullable enable
55

6+
using System;
7+
68
namespace Microsoft.TemplateEngine.Abstractions
79
{
810
/// <summary>
@@ -24,6 +26,7 @@ public interface IFileChange
2426
/// <summary>
2527
/// Gets the file content.
2628
/// </summary>
29+
[Obsolete("File contents are no longer available, the property always returns an empty byte array.")]
2730
byte[] Contents { get; }
2831
}
2932

‎src/Microsoft.TemplateEngine.Abstractions/IGenerator.cs

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ namespace Microsoft.TemplateEngine.Abstractions
1515
public interface IGenerator : IIdentifiedComponent
1616
{
1717
/// <summary>
18-
/// Generates <paramref name="template"/> with given parameters.
18+
/// Generates the <paramref name="template"/> with given parameters.
1919
/// </summary>
2020
/// <param name="environmentSettings">template engine environment settings.</param>
2121
/// <param name="template">template to generate.</param>
@@ -31,7 +31,7 @@ Task<ICreationResult> CreateAsync(
3131
CancellationToken cancellationToken);
3232

3333
/// <summary>
34-
/// Dry runs <paramref name="template"/> with given parameters.
34+
/// Dry runs the <paramref name="template"/> with given parameters.
3535
/// </summary>
3636
/// <param name="environmentSettings">template engine environment settings.</param>
3737
/// <param name="template">template to dry run.</param>
@@ -47,15 +47,18 @@ Task<ICreationEffects> GetCreationEffectsAsync(
4747
CancellationToken cancellationToken);
4848

4949
/// <summary>
50-
/// Returns <see cref="IParameterSet"/> for <paramref name="template"/>.
50+
/// Returns a <see cref="IParameterSet"/> for the given <paramref name="template"/>.
51+
/// This method returns the list of input parameters that can be set by the host / Edge before running the template.
52+
/// After setting the values the host should pass <see cref="IParameterSet"/> to <see cref="GetCreationEffectsAsync(IEngineEnvironmentSettings, ITemplate, IParameterSet, string, CancellationToken)"/> or <see cref="CreateAsync(IEngineEnvironmentSettings, ITemplate, IParameterSet, string, CancellationToken)"/> methods.
53+
/// Host may use <see cref="ConvertParameterValueToType(IEngineEnvironmentSettings, ITemplateParameter, string, out bool)"/> to convert input value to required parameter type.
5154
/// </summary>
5255
/// <param name="environmentSettings">template engine environment settings.</param>
5356
/// <param name="template">template to get parameters from.</param>
5457
/// <returns><see cref="IParameterSet"/> with parameters available in <paramref name="template"/>.</returns>
5558
IParameterSet GetParametersForTemplate(IEngineEnvironmentSettings environmentSettings, ITemplate template);
5659

5760
/// <summary>
58-
/// Gets <see cref="ITemplate"/> from given <see cref="IFileSystemInfo" /> configuration entry.
61+
/// Gets an <see cref="ITemplate"/> from the given <see cref="IFileSystemInfo" /> configuration entry.
5962
/// </summary>
6063
/// <param name="config">configuration file.</param>
6164
/// <param name="template">loaded template.</param>
@@ -66,21 +69,21 @@ Task<ICreationEffects> GetCreationEffectsAsync(
6669
bool TryGetTemplateFromConfigInfo(IFileSystemInfo config, out ITemplate template, IFileSystemInfo localeConfig, IFile hostTemplateConfigFile, string baselineName = null);
6770

6871
/// <summary>
69-
/// Gets <see cref="ITemplate"/>s from given <see cref="IFileSystemInfo" /> from given mount point <paramref name="source"/>.
72+
/// Scans the given mount point <paramref name="source"/> for templates and returns the list of <see cref="ITemplate"/>s that are found.
7073
/// </summary>
7174
/// <param name="source">the mount point to load templates from.</param>
7275
/// <param name="localizations">localization information for templates.</param>
7376
/// <returns>the list of templates found in <paramref name="source"/> mount point.</returns>
7477
IList<ITemplate> GetTemplatesAndLangpacksFromDir(IMountPoint source, out IList<ILocalizationLocator> localizations);
7578

7679
/// <summary>
77-
/// Converts <paramref name="untypedValue"/> to type defined for <paramref name="parameter"/>.
80+
/// Converts the given <paramref name="untypedValue"/> to the type of <paramref name="parameter"/>.
7881
/// </summary>
7982
/// <param name="environmentSettings">template engine environment settings.</param>
8083
/// <param name="parameter">template parameter defining the type.</param>
8184
/// <param name="untypedValue">the value to be converted to parameter type.</param>
8285
/// <param name="valueResolutionError">true if value could not be converted, false otherwise.</param>
83-
/// <returns>the converted value to type of <paramref name="parameter"/> or null if value cannot be converted.</returns>
86+
/// <returns>the converted <paramref name="untypedValue"/> value to the type of <paramref name="parameter"/> or null if the value cannot be converted.</returns>
8487
object ConvertParameterValueToType(IEngineEnvironmentSettings environmentSettings, ITemplateParameter parameter, string untypedValue, out bool valueResolutionError);
8588
}
8689
}

‎src/Microsoft.TemplateEngine.Abstractions/IIdentifiedComponent.cs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,14 @@
55

66
namespace Microsoft.TemplateEngine.Abstractions
77
{
8+
/// <summary>
9+
/// Defines a component loadable by <see cref="IComponentManager"/>.
10+
/// </summary>
811
public interface IIdentifiedComponent
912
{
13+
/// <summary>
14+
/// Gets the identifier of the component. Should be unique.
15+
/// </summary>
1016
Guid Id { get; }
1117
}
1218
}

‎src/Microsoft.TemplateEngine.Abstractions/IParameterSet.cs

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,27 @@
55

66
namespace Microsoft.TemplateEngine.Abstractions
77
{
8+
/// <summary>
9+
/// Defines a set of template parameters.
10+
/// </summary>
811
public interface IParameterSet
912
{
13+
/// <summary>
14+
/// Gets an enumerator iterating through the parameter definitions of the template.
15+
/// </summary>
1016
IEnumerable<ITemplateParameter> ParameterDefinitions { get; }
1117

12-
IEnumerable<string> RequiredBrokerCapabilities { get; }
13-
18+
/// <summary>
19+
/// Gets a collection of template parameters and their values.
20+
/// </summary>
1421
IDictionary<ITemplateParameter, object> ResolvedValues { get; }
1522

23+
/// <summary>
24+
/// Gets a parameter definition with the specified <paramref name="name"/>.
25+
/// </summary>
26+
/// <param name="name">Parameter name to get.</param>
27+
/// <param name="parameter">Retrieved parameter or null if the parameter is not found.</param>
28+
/// <returns>true if the parameter was retrieved, false otherwise.</returns>
1629
bool TryGetParameterDefinition(string name, out ITemplateParameter parameter);
1730
}
1831
}

‎src/Microsoft.TemplateEngine.Abstractions/IParameterSymbolLocalizationModel.cs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,14 @@
77

88
namespace Microsoft.TemplateEngine.Abstractions
99
{
10+
/// <summary>
11+
/// Defines a parameter localization model.
12+
/// </summary>
1013
public interface IParameterSymbolLocalizationModel
1114
{
15+
/// <summary>
16+
/// Gets the parameter name.
17+
/// </summary>
1218
string Name { get; }
1319

1420
/// <summary>

‎src/Microsoft.TemplateEngine.Abstractions/IPostAction.cs

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@
88

99
namespace Microsoft.TemplateEngine.Abstractions
1010
{
11+
/// <summary>
12+
/// Defines post action supported by the template.
13+
/// </summary>
1114
public interface IPostAction
1215
{
1316
/// <summary>
@@ -22,7 +25,7 @@ public interface IPostAction
2225
Guid ActionId { get; }
2326

2427
/// <summary>
25-
/// Gets a value indicating wheather the template instantiation should continue
28+
/// Gets a value indicating whether the template instantiation should continue
2629
/// in case of an error with this post action.
2730
/// </summary>
2831
bool ContinueOnError { get; }

‎src/Microsoft.TemplateEngine.Abstractions/IPostActionLocalizationModel.cs

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77

88
namespace Microsoft.TemplateEngine.Abstractions
99
{
10+
/// <summary>
11+
/// Defines <see cref="IPostAction"/> localization model.
12+
/// </summary>
1013
public interface IPostActionLocalizationModel
1114
{
1215
/// <summary>

‎src/Microsoft.TemplateEngine.Abstractions/ITemplate.cs

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,34 @@
55

66
namespace Microsoft.TemplateEngine.Abstractions
77
{
8+
/// <summary>
9+
/// Defines the template that can be run by <see cref="IGenerator"/>.
10+
/// </summary>
811
public interface ITemplate : ITemplateInfo
912
{
13+
/// <summary>
14+
/// Gets generator that runs the template.
15+
/// </summary>
1016
IGenerator Generator { get; }
1117

18+
/// <summary>
19+
/// Gets configuration file system entry.
20+
/// </summary>
1221
IFileSystemInfo Configuration { get; }
1322

23+
/// <summary>
24+
/// Gets localization file system entry.
25+
/// </summary>
1426
IFileSystemInfo LocaleConfiguration { get; }
1527

28+
/// <summary>
29+
/// Gets directory with template source files.
30+
/// </summary>
1631
IDirectory TemplateSourceRoot { get; }
1732

33+
/// <summary>
34+
/// Indicates whether he template should be created in a subdirectory under the output directory.
35+
/// </summary>
1836
bool IsNameAgreementWithFolderPreferred { get; }
1937
}
2038
}

‎src/Microsoft.TemplateEngine.Abstractions/Installer/IInstaller.cs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@
88

99
namespace Microsoft.TemplateEngine.Abstractions.Installer
1010
{
11+
/// <summary>
12+
/// Template package installer interface.
13+
/// To implement installer compatible with built-in template package providers, implement this interface.
14+
/// </summary>
1115
public interface IInstaller
1216
{
1317
/// <summary>

‎src/Microsoft.TemplateEngine.Abstractions/Installer/IInstallerFactory.cs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33

44
namespace Microsoft.TemplateEngine.Abstractions.Installer
55
{
6+
/// <summary>
7+
/// Template package installer factory interface.
8+
/// Implement this interface to register installer supported by built-in providers.
9+
/// </summary>
610
public interface IInstallerFactory : IIdentifiedComponent
711
{
812
/// <summary>

‎src/Microsoft.TemplateEngine.Abstractions/Installer/Result.cs renamed to ‎src/Microsoft.TemplateEngine.Abstractions/Installer/InstallerOperationResult.cs

File renamed without changes.

‎src/Microsoft.TemplateEngine.Abstractions/Mount/FileSystemInfoKind.cs

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,19 @@
33

44
namespace Microsoft.TemplateEngine.Abstractions.Mount
55
{
6+
/// <summary>
7+
/// Defines the kind of a <see cref="IFileSystemInfo"/> entry.
8+
/// </summary>
69
public enum FileSystemInfoKind
710
{
11+
/// <summary>
12+
/// Entry is a file.
13+
/// </summary>
814
File,
15+
16+
/// <summary>
17+
/// Entry is a directory.
18+
/// </summary>
919
Directory
1020
}
1121
}

‎src/Microsoft.TemplateEngine.Abstractions/Mount/IDirectory.cs

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,33 @@
66

77
namespace Microsoft.TemplateEngine.Abstractions.Mount
88
{
9+
/// <summary>
10+
/// Defines directory <see cref="IFileSystemInfo"/> entry.
11+
/// </summary>
912
public interface IDirectory : IFileSystemInfo
1013
{
11-
IEnumerable<IFileSystemInfo> EnumerateFileSystemInfos(string patten, SearchOption searchOption);
14+
/// <summary>
15+
/// Enumerates the <see cref="IFileSystemInfo"/> entries in the directory.
16+
/// </summary>
17+
/// <param name="pattern">Matching pattern for the entries, see <see cref="Directory.EnumerateFileSystemEntries(string, string, SearchOption)"/> for more details.</param>
18+
/// <param name="searchOption">Matching pattern for the entries, see <see cref="Directory.EnumerateFileSystemEntries(string, string, SearchOption)"/> for more details.</param>
19+
/// <returns>The enumerator to <see cref="IFileSystemInfo"/> entries in the directory.</returns>
20+
IEnumerable<IFileSystemInfo> EnumerateFileSystemInfos(string pattern, SearchOption searchOption);
1221

22+
/// <summary>
23+
/// Enumerates the <see cref="IFile"/> entries in the directory.
24+
/// </summary>
25+
/// <param name="pattern">Matching pattern for the entries, see <see cref="Directory.EnumerateFiles(string, string, SearchOption)"/> for more details.</param>
26+
/// <param name="searchOption">Matching pattern for the entries, see <see cref="Directory.EnumerateFiles(string, string, SearchOption)"/> for more details.</param>
27+
/// <returns>The enumerator to <see cref="IFile"/> entries in the directory.</returns>
1328
IEnumerable<IFile> EnumerateFiles(string pattern, SearchOption searchOption);
1429

30+
/// <summary>
31+
/// Enumerates the <see cref="IDirectory"/> entries in the directory.
32+
/// </summary>
33+
/// <param name="pattern">Matching pattern for the entries, see <see cref="Directory.EnumerateDirectories(string, string, SearchOption)"/> for more details.</param>
34+
/// <param name="searchOption">Matching pattern for the entries, see <see cref="Directory.EnumerateDirectories(string, string, SearchOption)"/> for more details.</param>
35+
/// <returns>The enumerator to <see cref="IDirectory"/> entries in the directory.</returns>
1536
IEnumerable<IDirectory> EnumerateDirectories(string pattern, SearchOption searchOption);
1637
}
1738
}

‎src/Microsoft.TemplateEngine.Abstractions/Mount/IFile.cs

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,15 @@
55

66
namespace Microsoft.TemplateEngine.Abstractions.Mount
77
{
8+
/// <summary>
9+
/// Defines a file <see cref="IFileSystemInfo"/> entry.
10+
/// </summary>
811
public interface IFile : IFileSystemInfo
912
{
13+
/// <summary>
14+
/// Opens the file stream for reading.
15+
/// </summary>
16+
/// <returns><see cref="Stream"/> that can be used for reading the file.</returns>
1017
Stream OpenRead();
1118
}
1219
}

‎src/Microsoft.TemplateEngine.Abstractions/Mount/IFileSystemInfo.cs

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,18 +3,41 @@
33

44
namespace Microsoft.TemplateEngine.Abstractions.Mount
55
{
6+
/// <summary>
7+
/// Defines a file system entry.
8+
/// </summary>
9+
/// <seealso cref="IDirectory"/>
10+
/// <seealso cref="IFile"/>
611
public interface IFileSystemInfo
712
{
13+
/// <summary>
14+
/// Returns true if file system entry exists, false otherwise.
15+
/// </summary>
816
bool Exists { get; }
917

18+
/// <summary>
19+
/// Gets the path to file system entry inside mount point <see cref="MountPoint"/>.
20+
/// </summary>
1021
string FullPath { get; }
1122

23+
/// <summary>
24+
/// Gets file system entry kind.
25+
/// </summary>
1226
FileSystemInfoKind Kind { get; }
1327

28+
/// <summary>
29+
/// Gets parent directory of file system entry.
30+
/// </summary>
1431
IDirectory Parent { get; }
1532

33+
/// <summary>
34+
/// Gets file system entry name.
35+
/// </summary>
1636
string Name { get; }
1737

38+
/// <summary>
39+
/// Gets mount point for file system entry.
40+
/// </summary>
1841
IMountPoint MountPoint { get; }
1942
}
2043
}

‎src/Microsoft.TemplateEngine.Abstractions/PublicAPI.Shipped.txt

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -261,8 +261,8 @@ Microsoft.TemplateEngine.Abstractions.TemplateParameterPriority.Suggested = 1 ->
261261
~const Microsoft.TemplateEngine.Abstractions.Installer.InstallerConstants.NuGetSourcesKey = "NuGetSources" -> string
262262
~Microsoft.TemplateEngine.Abstractions.IAllowDefaultIfOptionWithoutValue.DefaultIfOptionWithoutValue.get -> string
263263
~Microsoft.TemplateEngine.Abstractions.IAllowDefaultIfOptionWithoutValue.DefaultIfOptionWithoutValue.set -> void
264-
~Microsoft.TemplateEngine.Abstractions.IBaselineInfo.DefaultOverrides.get -> System.Collections.Generic.IReadOnlyDictionary<string, string>
265-
~Microsoft.TemplateEngine.Abstractions.IBaselineInfo.Description.get -> string
264+
Microsoft.TemplateEngine.Abstractions.IBaselineInfo.DefaultOverrides.get -> System.Collections.Generic.IReadOnlyDictionary<string!, string!>!
265+
Microsoft.TemplateEngine.Abstractions.IBaselineInfo.Description.get -> string?
266266
Microsoft.TemplateEngine.Abstractions.IComponentManager.OfType<T>() -> System.Collections.Generic.IEnumerable<T!>!
267267
Microsoft.TemplateEngine.Abstractions.IComponentManager.Register(System.Type! type) -> void
268268
Microsoft.TemplateEngine.Abstractions.IComponentManager.RegisterMany(System.Collections.Generic.IEnumerable<System.Type!>! typeList) -> void
@@ -334,7 +334,7 @@ Microsoft.TemplateEngine.Abstractions.IComponentManager.TryGetComponent<T>(Syste
334334
~Microsoft.TemplateEngine.Abstractions.ITemplate.TemplateSourceRoot.get -> Microsoft.TemplateEngine.Abstractions.Mount.IDirectory
335335
~Microsoft.TemplateEngine.Abstractions.Mount.IDirectory.EnumerateDirectories(string pattern, System.IO.SearchOption searchOption) -> System.Collections.Generic.IEnumerable<Microsoft.TemplateEngine.Abstractions.Mount.IDirectory>
336336
~Microsoft.TemplateEngine.Abstractions.Mount.IDirectory.EnumerateFiles(string pattern, System.IO.SearchOption searchOption) -> System.Collections.Generic.IEnumerable<Microsoft.TemplateEngine.Abstractions.Mount.IFile>
337-
~Microsoft.TemplateEngine.Abstractions.Mount.IDirectory.EnumerateFileSystemInfos(string patten, System.IO.SearchOption searchOption) -> System.Collections.Generic.IEnumerable<Microsoft.TemplateEngine.Abstractions.Mount.IFileSystemInfo>
337+
~Microsoft.TemplateEngine.Abstractions.Mount.IDirectory.EnumerateFileSystemInfos(string pattern, System.IO.SearchOption searchOption) -> System.Collections.Generic.IEnumerable<Microsoft.TemplateEngine.Abstractions.Mount.IFileSystemInfo>
338338
~Microsoft.TemplateEngine.Abstractions.Mount.IFile.OpenRead() -> System.IO.Stream
339339
~Microsoft.TemplateEngine.Abstractions.Mount.IFileSystemInfo.FullPath.get -> string
340340
~Microsoft.TemplateEngine.Abstractions.Mount.IFileSystemInfo.MountPoint.get -> Microsoft.TemplateEngine.Abstractions.Mount.IMountPoint
@@ -380,4 +380,3 @@ Microsoft.TemplateEngine.Abstractions.IComponentManager.TryGetComponent<T>(Syste
380380
~static Microsoft.TemplateEngine.Abstractions.Installer.UpdateResult.CreateFailure(Microsoft.TemplateEngine.Abstractions.Installer.UpdateRequest request, Microsoft.TemplateEngine.Abstractions.Installer.InstallerErrorCode error, string localizedFailureMessage) -> Microsoft.TemplateEngine.Abstractions.Installer.UpdateResult
381381
~static Microsoft.TemplateEngine.Abstractions.Installer.UpdateResult.CreateSuccess(Microsoft.TemplateEngine.Abstractions.Installer.UpdateRequest request, Microsoft.TemplateEngine.Abstractions.TemplatePackage.IManagedTemplatePackage templatePackage) -> Microsoft.TemplateEngine.Abstractions.Installer.UpdateResult
382382
~static Microsoft.TemplateEngine.Abstractions.Installer.UpdateResult.FromInstallResult(Microsoft.TemplateEngine.Abstractions.Installer.UpdateRequest request, Microsoft.TemplateEngine.Abstractions.Installer.InstallResult installResult) -> Microsoft.TemplateEngine.Abstractions.Installer.UpdateResult
383-

0 commit comments

Comments
 (0)