Skip to content
This repository has been archived by the owner on Aug 8, 2023. It is now read-only.

[ios, macos] Revised descriptions for abstract classes #9095

Merged
merged 6 commits into from
Jun 14, 2017
Merged

[ios, macos] Revised descriptions for abstract classes #9095

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
f2c0add
[ios, macos] revised descriptions for abstract classes
May 24, 2017
a2a4222
[ios, macos]revisions round 1
Jun 13, 2017
37e1710
[ios, macos] revisions part 2
Jun 14, 2017
b9a9df7
[ios, macos] revised MGLForegroundStyleLayer
Jun 14, 2017
ff784d3
[ios, macos] added subclass warnings
Jun 14, 2017
60fc2a2
[ios, macos] added subclass warnings
Jun 14, 2017
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
7 changes: 4 additions & 3 deletions platform/darwin/src/MGLForegroundStyleLayer.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,9 +11,10 @@ NS_ASSUME_NONNULL_BEGIN
`MGLForegroundStyleLayer` is an abstract superclass for style layers whose
content is defined by an `MGLSource` object.

Do not create instances of this class directly, and do not create your own
subclasses of this class. Instead, create instances of `MGLRasterStyleLayer`
and the concrete subclasses of `MGLVectorStyleLayer`.
Create instances of `MGLRasterStyleLayer` and the concrete subclasses of
`MGLVectorStyleLayer` in order to use `MGLForegroundStyleLayer`'s methods.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous wording (“do not create instances of this class”) matches Apple documentation. It’s fine to start with a positive description of what to do, but we still need to emphasize what not to do, because it’s very easy in Objective-C to fall into the trap of initializing an abstract superclass directly.

Additionally, it’s important to state that the developer shouldn’t create their own subclass of this class, due to how this class keeps track of a C++ object under the hood.

Do not create instances of `MGLForegroundStyleLayer` directly, and do not
create your own subclasses of this class.
*/
MGL_EXPORT
@interface MGLForegroundStyleLayer : MGLStyleLayer
Expand Down
8 changes: 4 additions & 4 deletions platform/darwin/src/MGLMultiPoint.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ NS_ASSUME_NONNULL_BEGIN
The `MGLMultiPoint` class is an abstract superclass used to define shapes
composed of multiple vertices.

You do not create instances of this class directly. Instead, you create
instances of the `MGLPolyline` or `MGLPolygon` classes. However, you can use
the method and properties of this class to access information about the
vertices of the line or polygon.
Create instances of `MGLPolyline` or `MGLPolygon` in order to use
properties of `MGLMultiPoint`. Do not create instances of `MGLMultiPoint`
directly. You can use the method and properties of this class to access
information about the vertices of the line or polygon.

Do not confuse `MGLMultiPoint` with `MGLPointCollection`, which represents a
collection of related but disconnected points.
Expand Down
9 changes: 4 additions & 5 deletions platform/darwin/src/MGLShape.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@ NS_ASSUME_NONNULL_BEGIN
constitute the content of a map – not only the overlays atop the map, but also
the content that forms the base map.

You do not create instances of this class directly or create subclasses of this
class. Instead, you create instances of `MGLPointAnnotation`,
`MGLPointCollection`, `MGLPolyline`, `MGLMultiPolyline`, `MGLPolygon`,
`MGLMultiPolygon`, or `MGLShapeCollection`. The shape classes correspond to the
<a href="https://tools.ietf.org/html/rfc7946#section-3.1">Geometry</a> object
Create instances of `MGLPointAnnotation`, `MGLPointCollection`, `MGLPolyline`,
`MGLMultiPolyline`, `MGLPolygon`, `MGLMultiPolygon`, or `MGLShapeCollection` in
order to use `MGLShape`'s methods. Do not create instances of `MGLShape` directly.
The shape classes correspond to the <a href="https://tools.ietf.org/html/rfc7946#section-3.1">Geometry</a> object
types in the GeoJSON standard, but some have nonstandard names for backwards
compatibility.

Expand Down
7 changes: 4 additions & 3 deletions platform/darwin/src/MGLSource.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,10 @@ NS_ASSUME_NONNULL_BEGIN
add and remove sources dynamically using methods such as
`-[MGLStyle addSource:]` and `-[MGLStyle sourceWithIdentifier:]`.

Do not create instances of this class directly, and do not create your own
subclasses of this class. Instead, create instances of `MGLShapeSource` and the
concrete subclasses of `MGLTileSource`, `MGLVectorSource` and `MGLRasterSource`.
Create instances of `MGLShapeSource` and the concrete subclasses of
`MGLTileSource`, `MGLVectorSource` and `MGLRasterSource` in order to use
`MGLMultiPoint`'s properties and methods. Do not create instances of `MGLSource`
directly.
*/
MGL_EXPORT
@interface MGLSource : NSObject
Expand Down
7 changes: 3 additions & 4 deletions platform/darwin/src/MGLStyleLayer.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,9 @@ NS_ASSUME_NONNULL_BEGIN
`MGLStyleLayer` object, which you can use to refine the map’s appearance. You
can also add and remove style layers dynamically.

Do not create instances of this class directly, and do not create your own
subclasses of this class. Instead, create instances of
`MGLBackgroundStyleLayer` and the concrete subclasses of
`MGLForegroundStyleLayer`.
Create instances of `MGLBackgroundStyleLayer` and the concrete subclasses of
`MGLForegroundStyleLayer` in order to use `MGLStyleLayer`'s properties and methods.
You do not create instances of `MGLStyleLayer` directly.

Do not add `MGLStyleLayer` objects to the `style` property of a `MGLMapView` before
`-mapView:didFinishLoadingStyle:` is called.
Expand Down
8 changes: 3 additions & 5 deletions platform/darwin/src/MGLStyleValue.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,11 +239,9 @@ MGL_EXPORT
defined by an `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, or
`MGLCompositeStyleFunction` object.

Do not create instances of this class directly, and do not create your own
subclasses of this class. Instead, use one of the class factory methods in
`MGLStyleValue` to create instances of the following concrete subclasses:
`MGLCameraStyleFunction`, `MGLSourceStyleFunction`, and
`MGLCompositeStyleFunction`.
Create instances of `MGLCameraStyleFunction`, `MGLSourceStyleFunction`, and
`MGLCompositeStyleFunction` in order to use `MGLStyleFunction`'s methods. Do
not create instances of `MGLStyleFunction` directly.

The `MGLStyleFunction` class takes a generic parameter `T` that indicates the
Foundation class being wrapped by this class.
Expand Down
6 changes: 3 additions & 3 deletions platform/darwin/src/MGLTileSource.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,9 +140,9 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) {
Mapbox-hosted tile set, view it in
<a href="https://www.mapbox.com/studio/tilesets/">Mapbox Studio’s Tilesets editor</a>.

Do not create instances of this class directly, and do not create your own
subclasses of this class. Instead, create instances of `MGLRasterSource` and
`MGLVectorSource`.
Create instances of `MGLRasterSource` and `MGLVectorSource` in order to use
`MGLTileSource`'s properties and methods. Do not create instances of `MGLTileSource`
directly.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would be great to have an admonition against subclassing MGLSource, MGLStyleFunction, MGLStyleLayer, MGLTileSource, and MGLVectorStyleLayer, as there is for MGLForegroundStyleLayer.

*/
MGL_EXPORT
@interface MGLTileSource : MGLSource
Expand Down
7 changes: 3 additions & 4 deletions platform/darwin/src/MGLVectorStyleLayer.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,9 @@ NS_ASSUME_NONNULL_BEGIN
`MGLVectorStyleLayer` is an abstract superclass for style layers whose content
is defined by an `MGLShapeSource` or `MGLVectorSource` object.

Do not create instances of this class directly, and do not create your own
subclasses of this class. Instead, create instances of the following concrete
subclasses: `MGLCircleStyleLayer`, `MGLFillStyleLayer`, `MGLLineStyleLayer`,
and `MGLSymbolStyleLayer`.
Create instances of `MGLCircleStyleLayer`, `MGLFillStyleLayer`, `MGLLineStyleLayer`,
and `MGLSymbolStyleLayer` in order to use `MGLVectorStyleLayer`'s properties and
methods. Do not create instances of `MGLVectorStyleLayer` directly.
*/
MGL_EXPORT
@interface MGLVectorStyleLayer : MGLForegroundStyleLayer
Expand Down
2 changes: 1 addition & 1 deletion platform/ios/src/MGLUserLocation.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ NS_ASSUME_NONNULL_BEGIN
/**
The MGLUserLocation class defines a specific type of annotation that identifies
the user’s current location. You do not create instances of this class
directly. Instead, you retrieve an existing MGLUserLocation object from the
directly. Instead, you retrieve an existing `MGLUserLocation` object from the
`userLocation` property of the map view displayed in your application.
*/
@interface MGLUserLocation : NSObject <MGLAnnotation, NSSecureCoding>
Expand Down