Skip to content
This repository has been archived by the owner on Sep 16, 2024. It is now read-only.

Commit

Permalink
docs: fix grammar mistakes in docs (#340)
Browse files Browse the repository at this point in the history
  • Loading branch information
halildurmus authored Aug 2, 2023
1 parent 64967d3 commit a420d0d
Show file tree
Hide file tree
Showing 31 changed files with 125 additions and 124 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ interface class IIterable<T> extends IInspectable {
/// Creates an instance of [IIterable] from the given [ptr].
///
/// [T] must be of type `bool`, `DateTime`, `double`, `Duration`, `Guid`,
/// `int`, `Object?`, `String`, `Uri?`, `IInspectable?` (e.g. `StorageFile?`),
/// `WinRTEnum` (e.g. `DeviceClass`), or `WinRTStruct` (e.g.
/// `BasicGeoposition`).
/// `int`, `Object?`, `String`, `Uri?`, `IInspectable?` (e.g.,
/// `StorageFile?`), `WinRTEnum` (e.g., `DeviceClass`), or `WinRTStruct`
/// (e.g., `BasicGeoposition`).
///
/// [doubleType] must be specified if [T] is `double`.
/// ```dart
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,9 @@ abstract interface class IIterator<T> extends IInspectable {
/// Creates an instance of [IIterator] from the given [ptr].
///
/// [T] must be of type `bool`, `DateTime`, `double`, `Duration`, `Guid`,
/// `int`, `Object?`, `String`, `Uri?`, `IInspectable?` (e.g. `StorageFile?`),
/// `WinRTEnum` (e.g. `DeviceClass`), or `WinRTStruct` (e.g.
/// `BasicGeoposition`).
/// `int`, `Object?`, `String`, `Uri?`, `IInspectable?` (e.g.,
/// `StorageFile?`), `WinRTEnum` (e.g., `DeviceClass`), or `WinRTStruct`
/// (e.g., `BasicGeoposition`).
///
/// [doubleType] must be specified if [T] is `double`.
/// ```dart
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,10 @@ abstract interface class IKeyValuePair<K, V> extends IInspectable {
/// Creates an instance of [IKeyValuePair] from the given [ptr].
///
/// [K] must be of type `Guid`, `int`, `Object`, `String`, `Uri`, or
/// `WinRTEnum` (e.g. `PedometerStepKind`).
/// `WinRTEnum` (e.g., `PedometerStepKind`).
///
/// [V] must be of type `Object?`, `String`, `IInspectable?` (e.g.
/// `IJsonValue?`), or `WinRTEnum` (e.g. `ChatMessageStatus`).
/// [V] must be of type `Object?`, `String`, `IInspectable?` (e.g.,
/// `IJsonValue?`), or `WinRTEnum` (e.g., `ChatMessageStatus`).
///
/// [creator] must be specified if [V] is `IInspectable?`.
/// ```dart
Expand Down
8 changes: 4 additions & 4 deletions packages/windows_foundation/lib/src/collections/imap.dart
Original file line number Diff line number Diff line change
Expand Up @@ -91,13 +91,13 @@ abstract interface class IMap<K, V> extends IInspectable
/// Creates an instance of [IMap] from the given [ptr] and [iterableIid].
///
/// [iterableIid] must be the IID of the `IIterable<IKeyValuePair<K, V>>`
/// interface (e.g. `'{fe2f3d47-5d47-5499-8374-430c7cda0204}'`).
/// interface (e.g., `'{fe2f3d47-5d47-5499-8374-430c7cda0204}'`).
///
/// [K] must be of type `Guid`, `int`, `Object`, `String`, `Uri`, or
/// `WinRTEnum` (e.g. `PedometerStepKind`).
/// `WinRTEnum` (e.g., `PedometerStepKind`).
///
/// [V] must be of type `Object?`, `String`, `IInspectable?` (e.g.
/// `IJsonValue?`), or `WinRTEnum` (e.g. `ChatMessageStatus`).
/// [V] must be of type `Object?`, `String`, `IInspectable?` (e.g.,
/// `IJsonValue?`), or `WinRTEnum` (e.g., `ChatMessageStatus`).
///
/// [creator] must be specified if [V] is a `IInspectable?`.
/// ```dart
Expand Down
8 changes: 4 additions & 4 deletions packages/windows_foundation/lib/src/collections/imapview.dart
Original file line number Diff line number Diff line change
Expand Up @@ -49,13 +49,13 @@ abstract interface class IMapView<K, V> extends IInspectable
/// Creates an instance of [IMapView] from the given [ptr] and [iterableIid].
///
/// [iterableIid] must be the IID of the `IIterable<IKeyValuePair<K, V>>`
/// interface (e.g. `'{dfabb6e1-0411-5a8f-aa87-354e7110f099}'`).
/// interface (e.g., `'{dfabb6e1-0411-5a8f-aa87-354e7110f099}'`).
///
/// [K] must be of type `Guid`, `int`, `Object`, `String`, `Uri`, or
/// `WinRTEnum` (e.g. `PedometerStepKind`).
/// `WinRTEnum` (e.g., `PedometerStepKind`).
///
/// [V] must be of type `Object?`, `String`, `IInspectable?` (e.g.
/// `IJsonValue?`), or `WinRTEnum` (e.g. `ChatMessageStatus`).
/// [V] must be of type `Object?`, `String`, `IInspectable?` (e.g.,
/// `IJsonValue?`), or `WinRTEnum` (e.g., `ChatMessageStatus`).
///
/// [creator] must be specified if [V] is `IInspectable?`.
/// ```dart
Expand Down
8 changes: 4 additions & 4 deletions packages/windows_foundation/lib/src/collections/ivector.dart
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,13 @@ abstract interface class IVector<T> extends IInspectable

/// Creates an instance of [IVector] from the given [ptr] and [iterableIid].
///
/// [iterableIid] must be the IID of the `IIterable<T>` interface (e.g.
/// [iterableIid] must be the IID of the `IIterable<T>` interface (e.g.,
/// `'{9ac00304-83ea-5688-87b6-ae38aab65d0b}'`).
///
/// [T] must be of type `bool`, `DateTime`, `double`, `Duration`, `Guid`,
/// `int`, `Object?`, `String`, `Uri?`, `IInspectable?` (e.g. `StorageFile?`),
/// `WinRTEnum` (e.g. `DeviceClass`), or `WinRTStruct` (e.g.
/// `BasicGeoposition`).
/// `int`, `Object?`, `String`, `Uri?`, `IInspectable?` (e.g.,
/// `StorageFile?`), `WinRTEnum` (e.g., `DeviceClass`), or `WinRTStruct`
/// (e.g., `BasicGeoposition`).
///
/// [doubleType] must be specified if [T] is `double`.
/// ```dart
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -52,13 +52,13 @@ abstract interface class IVectorView<T> extends IInspectable
/// Creates an instance of [IVectorView] from the given [ptr] and
/// [iterableIid].
///
/// [iterableIid] must be the IID of the `IIterable<T>` interface (e.g.
/// [iterableIid] must be the IID of the `IIterable<T>` interface (e.g.,
/// `'{9ac00304-83ea-5688-87b6-ae38aab65d0b}'`).
///
/// [T] must be of type `bool`, `DateTime`, `double`, `Duration`, `Guid`,
/// `int`, `Object?`, `String`, `Uri?`, `IInspectable?` (e.g. `StorageFile?`),
/// `WinRTEnum` (e.g. `DeviceClass`), or `WinRTStruct` (e.g.
/// `BasicGeoposition`).
/// `int`, `Object?`, `String`, `Uri?`, `IInspectable?` (e.g.,
/// `StorageFile?`), `WinRTEnum` (e.g., `DeviceClass`), or `WinRTStruct`
/// (e.g., `BasicGeoposition`).
///
/// [doubleType] must be specified if [T] is `double`.
/// ```dart
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import 'package:win32/win32.dart';
extension IUnknownHelpers on IUnknown {
/// Casts this COM object to an interface specified in [iid].
///
/// [creator] must be the constructor of the class to be casted to (e.g.
/// [creator] must be the constructor of the class to be casted to (e.g.,
/// `ICalendar.fromPtr`).
///
/// Throws a [WindowsException] if the cast fails.
Expand All @@ -19,7 +19,7 @@ extension IUnknownHelpers on IUnknown {

/// Tries to cast this COM object to an interface specified in [iid].
///
/// [creator] must be the constructor of the class to be casted to (e.g.
/// [creator] must be the constructor of the class to be casted to (e.g.,
/// `ICalendar.fromPtr`).
///
/// Returns `null` if the cast fails.
Expand Down
12 changes: 6 additions & 6 deletions packages/windows_foundation/lib/src/helpers.dart
Original file line number Diff line number Diff line change
Expand Up @@ -45,13 +45,13 @@ Pointer<COMObject> activateClass(String className,
/// Creates the activation factory for the specified Windows Runtime class in
/// [className].
///
/// [creator] must be the constructor of the class to be created (e.g.
/// [creator] must be the constructor of the class to be created (e.g.,
/// `ICalendarFactory.fromPtr`).
///
/// [className] must be the name of the Windows Runtime class (e.g.
/// [className] must be the name of the Windows Runtime class (e.g.,
/// `Windows.Globalization.Calendar`).
///
/// [iid] must be the IID of the object to be created (e.g.
/// [iid] must be the IID of the object to be created (e.g.,
/// `IID_ICalendarFactory`).
///
/// ```dart
Expand Down Expand Up @@ -88,13 +88,13 @@ T createActivationFactory<T extends IInspectable>(

/// Creates a WinRT object.
///
/// [creator] must be the constructor of the class to be created (e.g.
/// [creator] must be the constructor of the class to be created (e.g.,
/// `ICalendar.fromPtr`).
///
/// [className] must be an activatable Windows Runtime class (e.g.
/// [className] must be an activatable Windows Runtime class (e.g.,
/// `Windows.Globalization.Calendar`).
///
/// [iid] must be the IID of the object to be created (e.g. `IID_ICalendar`).
/// [iid] must be the IID of the object to be created (e.g., `IID_ICalendar`).
///
/// ```dart
/// final calendar = createObject(ICalendar.fromPtr,
Expand Down
4 changes: 2 additions & 2 deletions packages/windows_foundation/lib/src/iasyncoperation.dart
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,8 @@ abstract interface class IAsyncOperation<TResult> extends IInspectable
/// Creates an instance of [IAsyncOperation] from the given `ptr`.
///
/// [TResult] must be of type `bool`, `double`, `Guid`, `int`, `Object?`,
/// `String`, `Uri?`, `IInspectable?` (e.g. `StorageFile?`), `WinRTEnum` (e.g.
/// `LaunchUriStatus`), or `WinRTStruct` (e.g. `LoadMoreItemsResult`).
/// `String`, `Uri?`, `IInspectable?` (e.g., `StorageFile?`), `WinRTEnum`
/// (e.g., `LaunchUriStatus`), or `WinRTStruct` (e.g., `LoadMoreItemsResult`).
///
/// [doubleType] must be specified if [TResult] is `double`.
/// ```darts
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ extension WinRTFlagsEnumListToUint32ArrayConversion on List<WinRTFlagsEnum> {
extension Int32ArrayToWinRTEnumListConversion on Pointer<Int32> {
/// Creates a [List] of [T]s from `Pointer<Int32>`.
///
/// [T] must be [WinRTEnum] (e.g. `DeviceClass`).
/// [T] must be [WinRTEnum] (e.g., `DeviceClass`).
///
/// [creator] must be specified for [T] (e.g. `DeviceClass.from`).
/// [creator] must be specified for [T] (e.g., `DeviceClass.from`).
///
/// [length] must not be greater than the number of elements stored inside the
/// `Pointer<Int32>`.
Expand All @@ -59,9 +59,9 @@ extension Int32ArrayToWinRTEnumListConversion on Pointer<Int32> {
extension Uint32ArrayToWinRTEnumListConversion on Pointer<Uint32> {
/// Creates a [List] of [T]s from `Pointer<Uint32>`.
///
/// [T] must be [WinRTFlagsEnum] (e.g. `FileAttributes`).
/// [T] must be [WinRTFlagsEnum] (e.g., `FileAttributes`).
///
/// [creator] must be specified for [T] (e.g. `FileAttributes.from`).
/// [creator] must be specified for [T] (e.g., `FileAttributes.from`).
///
/// [length] must not be greater than the number of elements stored inside the
/// `Pointer<Uint32>`.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ extension ObjectConversion on Object {
if (self is List<String>) return self.toPropertyValue();
if (self is List<Uri?>) return self.toPropertyValue();

// TODO(halildurmus): Support boxing enums and other structs (e.g.
// TODO(halildurmus): Support boxing enums and other structs (e.g.,
// BasicGeoposition)
// https://github.com/dart-windows/dartwinrt/issues/307

Expand All @@ -118,9 +118,9 @@ extension ObjectListToVTablePointerArrayConversion on List<Object?> {
extension COMObjectArrayToObjectListConversion on Pointer<COMObject> {
/// Creates a [List] of [T]s from `Pointer<COMObject>`.
///
/// [T] must be `IInspectable?` (e.g. `HostName?`).
/// [T] must be `IInspectable?` (e.g., `HostName?`).
///
/// [creator] must be specified for [T] (e.g. `HostName.fromPtr`).
/// [creator] must be specified for [T] (e.g., `HostName.fromPtr`).
///
/// [length] must not be greater than the number of elements stored inside the
/// `Pointer<COMObject>`.
Expand Down
6 changes: 3 additions & 3 deletions packages/windows_foundation/lib/src/ireference.dart
Original file line number Diff line number Diff line change
Expand Up @@ -29,12 +29,12 @@ abstract interface class IReference<T> extends IInspectable {
/// Creates an instance of [IReference] from the given [ptr] and
/// [referenceIid].
///
/// [referenceIid] must be the IID of the `IReference<T>` interface (e.g.
/// [referenceIid] must be the IID of the `IReference<T>` interface (e.g.,
/// `'{513ef3af-e784-5325-a91e-97c2b8111cf3}'`).
///
/// [T] must be of type `bool`, `DateTime?`, `double?`, `Duration?`, `Guid?`,
/// `int?`, `String?`, `WinRTEnum?` (e.g. `WebErrorStatus?`), or
/// `WinRTStruct?` (e.g. `BasicGeoposition?`).
/// `int?`, `String?`, `WinRTEnum?` (e.g., `WebErrorStatus?`), or
/// `WinRTStruct?` (e.g., `BasicGeoposition?`).
///
/// [enumCreator] must be specified if [T] is `WinRTEnum?`.
/// ```dart
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ final class InitializeWithWindow {
/// used in a desktop app.
///
/// [target] must be a WinRT object that implements the
/// `IInitializeWithWindow` interface (e.g. `FileOpenPicker`).
/// `IInitializeWithWindow` interface (e.g., `FileOpenPicker`).
///
/// [hwnd] represents the handle of the window to be used as the owner window.
/// If omitted, the current console or shell's desktop window is used.
Expand Down
12 changes: 6 additions & 6 deletions packages/winrtgen/lib/src/models/generic_type.dart
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,22 @@ import 'type_arg_kind.dart';
sealed class GenericType {
const GenericType(this.fullyQualifiedType);

/// The fully qualified type (e.g. Windows.Foundation.IReference`1).
/// The fully qualified type (e.g., Windows.Foundation.IReference`1).
final String fullyQualifiedType;

/// The short name of the type (e.g. `IReference`).
/// The short name of the type (e.g., `IReference`).
String get shortName => lastComponent(stripGenerics(fullyQualifiedType));

@override
String toString() => shortName;
}

/// Represents a WinRT generic type with one type argument (e.g.
/// Represents a WinRT generic type with one type argument (e.g.,
/// Windows.Foundation.IAsyncOperation`1).
final class GenericTypeWithOneTypeArg extends GenericType {
const GenericTypeWithOneTypeArg(super.fullyQualifiedType, this.typeArgKinds);

/// The [TypeArgKind]s for this generic type (e.g. `TypeArgKind.bool_`,
/// The [TypeArgKind]s for this generic type (e.g., `TypeArgKind.bool_`,
/// `TypeArgKind.string`).
final Set<TypeArgKind> typeArgKinds;

Expand Down Expand Up @@ -61,13 +61,13 @@ final class GenericTypeWithOneTypeArg extends GenericType {
}
}

/// Represents a WinRT generic type with two type arguments (e.g.
/// Represents a WinRT generic type with two type arguments (e.g.,
/// Windows.Foundation.Collections.IMap`2).
final class GenericTypeWithTwoTypeArgs extends GenericType {
const GenericTypeWithTwoTypeArgs(
super.fullyQualifiedType, this.typeArgKindPairs);

/// The [TypeArgKind] pairs for this generic type (e.g.
/// The [TypeArgKind] pairs for this generic type (e.g.,
/// `(TypeArgKind.string, TypeArgKind.string)`,
/// `(TypeArgKind.string, TypeArgKind.nullableObject)`).
final Set<(TypeArgKind, TypeArgKind)> typeArgKindPairs;
Expand Down
9 changes: 5 additions & 4 deletions packages/winrtgen/lib/src/projections/base.dart
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,22 @@ abstract base class BaseProjection {
final String comment;
final TypeDef typeDef;

/// Returns the path to the folder where the current class is located (e.g.
/// Returns the path to the folder where the current class is located (e.g.,
/// `windows_foundation/lib/src` for `Windows.Foundation.Point`).
String get currentFolderPath => folderFromType(typeDef.name);

/// Whether the [typeDef] has the `DeprecatedAttribute`.
bool get isDeprecated => typeDef.isDeprecated;

/// Returns the fully-qualified name of the [typeDef] (e.g.
/// Returns the fully-qualified name of the [typeDef] (e.g.,
/// `Windows.Globalization.Calendar`, `Windows.Foundation.IReference`1`).
String get name => typeDef.fullyQualifiedName;

/// Returns the shorter name of the [typeDef] (e.g. `IAsyncInfo`, `Calendar`).
/// Returns the shorter name of the [typeDef] (e.g., `IAsyncInfo`,
/// `Calendar`).
String get shortName => outerType(typeDef.shortName);

/// Returns the package name for the [typeDef] (e.g. `windows_foundation`
/// Returns the package name for the [typeDef] (e.g., `windows_foundation`
/// for `Windows.Foundation.Point`).
String get packageName => typeDef.packageName;

Expand Down
8 changes: 4 additions & 4 deletions packages/winrtgen/lib/src/projections/generic_interface.dart
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ ${projections.join('\n')}
final class GenericInterfaceProjection extends InterfaceProjection {
GenericInterfaceProjection._(super.typeDef, this.typeArgs);

/// The type arguments of the interface (e.g. `[TypeArgKind.string]`,
/// The type arguments of the interface (e.g., `[TypeArgKind.string]`,
/// `[TypeArgKind.string, TypeArgKind.nullableObject]`).
final List<TypeArgKind> typeArgs;

Expand All @@ -64,7 +64,7 @@ final class GenericInterfaceProjection extends InterfaceProjection {
/// ```
///
/// [typeArg2] must be specified if [fullyQualifiedType] has two type
/// arguments (e.g. `Windows.Foundation.Collections.IMap`2`).
/// arguments (e.g., `Windows.Foundation.Collections.IMap`2`).
///
/// ```dart
/// final projection = GenericInterfaceProjection.from(
Expand Down Expand Up @@ -114,7 +114,7 @@ final class GenericInterfaceProjection extends InterfaceProjection {

String get formattedTypeArgs => typeArgs.map(_formatTypeArgKind).join(', ');

/// The generic type parameters that are used in the class header (e.g.
/// The generic type parameters that are used in the class header (e.g.,
/// `<K, V>`, `<T>`).
String get typeParams {
final params = typeDef.genericParams
Expand All @@ -125,7 +125,7 @@ final class GenericInterfaceProjection extends InterfaceProjection {
return params.isNotEmpty ? '<${params.join(', ')}>' : '';
}

/// The class name of the interface (e.g. `_IMapStringString`,
/// The class name of the interface (e.g., `_IMapStringString`,
/// `_IVectorIInspectable`).
String get className {
final args = typeArgs
Expand Down
8 changes: 4 additions & 4 deletions packages/winrtgen/lib/src/projections/interface.dart
Original file line number Diff line number Diff line change
Expand Up @@ -106,10 +106,10 @@ const IID_$shortName = ${quote(typeDef.iid)};''';
factory $shortName.from(IInspectable interface) =>
$shortName.fromPtr(interface.toInterface(IID_$shortName));''';

// WinRT interfaces don't inherit in metadata (e.g. IAsyncInfo has no parent),
// but all WinRT interfaces have a base type of IInspectable as far as the
// COM vtable is concerned. They contain the methods of IInspectable (as well
// as IUnknown, from which IInspectable itself inherits).
// WinRT interfaces don't inherit in metadata (e.g., IAsyncInfo), but all
// WinRT interfaces have a base type of IInspectable as far as the COM vtable
// is concerned. They contain the methods of IInspectable (as well as
// IUnknown, from which IInspectable itself inherits).
//
// For more information, see the Interfaces section of the documentation here:
// https://learn.microsoft.com/uwp/winrt-cref/winrt-type-system
Expand Down
4 changes: 2 additions & 2 deletions packages/winrtgen/lib/src/projections/method.dart
Original file line number Diff line number Diff line change
Expand Up @@ -123,12 +123,12 @@ base class MethodProjection {
return params;
}

/// The parameters exposed by a projected Dart method (e.g. `int age`,
/// The parameters exposed by a projected Dart method (e.g., `int age`,
/// `int index, String value`).
String get methodParams =>
exposedParams.map((param) => param.paramProjection).join(', ');

/// The return type of the method (e.g. `String`).
/// The return type of the method (e.g., `String`).
String get returnType => paramProjection.type;

/// Type projection of the return type parameter.
Expand Down
Loading

0 comments on commit a420d0d

Please sign in to comment.