averello/swift-mirror
1
0
Fork 0
mirror of https://github.com/apple/swift.git synced 2025-12-21 12:14:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

stdlib: extinguish \brief and \c

Browse Source 
Swift SVN r18261
This commit is contained in:
Dmitri Hrybenko
2014-05-17 18:10:51 +00:00
parent 8215dff6c3
commit a4d9dcf1a7
19 changed files with 310 additions and 316 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
stdlib/core/Algorithm.swift
View File

@@ -346,9 +346,8 @@ func split<Seq: Sliceable, R:LogicValue>(
return result
}
/// \brief Return true iff the elements of e1 are equal to the initial
/// elements of e2
/// Return true iff the elements of `e1` are equal to the initial
/// elements of `e2`.
func startsWith<
S0: Sequence, S1: Sequence
where
@@ -476,8 +475,8 @@ func lexicographicalCompare<
}
}
/// Return true iff a1 precedes a2 in a lexicographical ("dictionary")
/// ordering, using less as the comparison between elements.
/// Return true iff `a1` precedes `a2` in a lexicographical ("dictionary")
/// ordering, using `less` as the comparison between elements.
func lexicographicalCompare<
S1 : Sequence, S2 : Sequence
where
@@ -507,7 +506,7 @@ func lexicographicalCompare<
}
}
/// \brief return true iff an element in seq satisfies predicate
/// Return `true` iff an element in `seq` satisfies `predicate`.
func contains<
S: Sequence, L: LogicValue
>(seq: S, predicate: (S.GeneratorType.Element)->L) -> Bool {
@@ -519,7 +518,7 @@ func contains<
return false
}
/// \brief return true iff x is in seq
/// Return `true` iff `x` is in `seq`.
func contains<
S: Sequence where S.GeneratorType.Element: Equatable
>(seq: S, x: S.GeneratorType.Element) -> Bool {

2
stdlib/core/Bool.swift
View File

@@ -16,7 +16,7 @@
struct Bool {
var value: Builtin.Int1
/// \brief Default-initialize Boolean value to \c false.
/// Default-initialize Boolean value to `false`.
@transparent
init() { value = Builtin.trunc_Word_Int1(0.value) }

17
stdlib/core/BridgeObjectiveC.swift
View File

@@ -10,7 +10,7 @@
//
//===----------------------------------------------------------------------===//
/// \brief Invokes body with an UnsafePointer to arg and returns the
/// Invokes `body` with an `UnsafePointer` to `arg` and returns the
/// result. Useful for calling Objective-C APIs that take "in/out"
/// parameters (and default-constructible "out" parameters) by pointer
func withUnsafePointer<T, Result>(
@@ -21,8 +21,7 @@ func withUnsafePointer<T, Result>(
return body(UnsafePointer<T>(Builtin.addressof(&arg)))
}
/// \brief Like withUnsafePointer, but passes pointers to arg0 and
/// arg1
/// Like `withUnsafePointer`, but passes pointers to `arg0` and `arg1`.
func withUnsafePointers<A0, A1, Result>(
inout arg0: A0,
inout arg1: A1,
@@ -35,8 +34,8 @@ func withUnsafePointers<A0, A1, Result>(
}
}
/// \brief Like withUnsafePointer, but passes pointers to arg0, arg1,
/// and arg2
/// Like `withUnsafePointer`, but passes pointers to `arg0`, `arg1`,
/// and `arg2`.
func withUnsafePointers<A0, A1, A2, Result>(
inout arg0: A0,
inout arg1: A1,
@@ -52,12 +51,12 @@ func withUnsafePointers<A0, A1, A2, Result>(
}
}
/// \brief Invokes body with an UnsafePointer to a nil T, sets arg to
/// the value of that T (or .None if the T is still nil), and returns
/// the result of the invocation
/// Invokes `body` with an `UnsafePointer` to a `nil` `T`, sets `arg` to
/// the value of that `T` (or `.None` if the `T` is still `nil`), and returns
/// the result of the invocation.
///
/// Useful for calling Objective-C APIs that take class instances by
/// pointer as @autorelease "out" parameters.
/// pointer as `@autorelease` "out" parameters.
func withUnsafePointerToObject<T: AnyObject, Result>(
inout arg: T?,
body: (UnsafePointer<ImplicitlyUnwrappedOptional<T>>)->Result

6
stdlib/core/Builtin.swift
View File

@@ -10,9 +10,9 @@
//
//===----------------------------------------------------------------------===//
/// \brief Definitions that make elements of Builtin usable in real
/// code without gobs of boilerplate. These APIs will probably *not*
/// be exposed outside the stdlib.
// Definitions that make elements of Builtin usable in real
// code without gobs of boilerplate. These APIs will probably *not*
// be exposed outside the stdlib.
@transparent
func sizeof<T>(_:T.Type) -> Int {

2
stdlib/core/CString.swift
View File

@@ -54,7 +54,7 @@ struct CString :
return _bytesPtr.isNull()
}
/// \brief From a CString with possibly-transient lifetime, create a
/// From a `CString` with possibly-transient lifetime, create a
/// nul-terminated array of 'C' char.
func persist() -> CChar[] {
var length = _strlen(self)

4
stdlib/core/Character.swift
View File

@@ -19,7 +19,7 @@ struct IntEncoder : Sink {
}
}
/// \brief Character represents some Unicode grapheme cluster as
/// `Character` represents some Unicode grapheme cluster as
/// defined by a canonical, localized, or otherwise tailored
/// segmentation algorithm.
enum Character :
@@ -83,7 +83,7 @@ enum Character :
}
}
/// \brief return the index of the lowest byte that is 0xFF, or 8 if
/// Return the index of the lowest byte that is 0xFF, or 8 if
/// there is none
static func _smallSize(value: UInt64) -> Int {
var mask: UInt64 = 0xFF

11
stdlib/core/HeapBuffer.swift
View File

@@ -23,11 +23,11 @@ func swift_bufferAllocate(
@asmname("malloc_size")
func c_malloc_size(heapMemory: UnsafePointer<Void>) -> Int
/// \brief a class containing an ivar "value" of type Value, and
/// A class containing an ivar "value" of type Value, and
/// containing storage for an array of Element whose size is
/// determined at create time.
///
/// The analogous C++-ish class template would be:
/// The analogous C++-ish class template would be::
///
/// template <class Value, class Element>
/// struct HeapBuffer {
@@ -104,8 +104,7 @@ struct HeapBuffer<Value, Element> : LogicValue, Equatable {
return UnsafePointer(HeapBuffer._elementOffset() + _address)
}
/// \brief Return the actual number of Elements we can possibly
/// store.
/// Return the actual number of `Elements` we can possibly store.
func _capacity() -> Int {
let allocatedSize = c_malloc_size(UnsafePointer(_address))
return (allocatedSize - HeapBuffer._elementOffset())
@@ -120,8 +119,8 @@ struct HeapBuffer<Value, Element> : LogicValue, Equatable {
self.storage = storage
}
/// \brief Create a HeapBuffer with self.value = initializer and
/// self._capacity() >= capacity.
/// Create a `HeapBuffer` with `self.value = initializer` and
/// `self._capacity() >= capacity`.
init(
_ storageClass: HeapBufferStorageBase.Type,
_ initializer: Value, _ capacity: Int

24
stdlib/core/LifetimeManager.swift
View File

@@ -16,11 +16,11 @@
@asmname("swift_keepAlive")
func swift_keepAlive<T>(inout _: T)
/// \brief An instance of this struct keeps the references registered with it
/// at +1 reference count until the call to \c release().
/// An instance of this struct keeps the references registered with it
/// at +1 reference count until the call to `release()`.
///
/// It is absolutely necessary to call \c release(). Forgetting to call
/// \c release() will not cause a memory leak. Instead, the managed objects will be
/// It is absolutely necessary to call `release()`. Forgetting to call
/// `release()` will not cause a memory leak. Instead, the managed objects will be
/// released earlier than expected.
///
/// This class can be used to extend lifetime of objects to pass UnsafePointers
@@ -49,14 +49,14 @@ class LifetimeManager {
// put(Builtin.castToNativeObject(obj))
// }
/// \brief Call this function to end the forced lifetime extension.
/// Call this function to end the forced lifetime extension.
func release() {
_fixLifetime(_managedRefs.owner)
_releaseCalled = true
}
}
/// \brief Evaluate f() and return its result, ensuring that x is not
/// Evaluate `f()` and return its result, ensuring that `x` is not
/// destroyed before f returns.
func withExtendedLifetime<T, Result>(
x: T, f: ()->Result
@@ -66,7 +66,7 @@ func withExtendedLifetime<T, Result>(
return result
}
/// \brief Evaluate f(x) and return its result, ensuring that x is not
/// Evaluate `f(x)` and return its result, ensuring that `x` is not
/// destroyed before f returns.
func withExtendedLifetime<T, Result>(
x: T, f: (T)->Result
@@ -79,7 +79,7 @@ func withExtendedLifetime<T, Result>(
// FIXME: this function can die once <rdar://problem/14497260> (need
// support for CF bridging) is solved.
/// \brief Pass a given object as a COpaquePointer at +0 to the given
/// Pass a given object as a `COpaquePointer` at +0 to the given
/// function, returning its result. This function is useful for
/// calling CoreFoundation functions on NS types that are toll-free
/// bridged; you have to declare these functions as taking
@@ -93,9 +93,9 @@ func withObjectAtPlusZero<Result>(x: AnyObject, f: (COpaquePointer)->Result) ->
extension String {
/// \brief Invoke f on the contents of this string, represented as
/// Invoke `f` on the contents of this string, represented as
/// a nul-terminated array of char, ensuring that the array's
/// lifetime extends through the execution of f
/// lifetime extends through the execution of `f`.
func withCString<Result>(
f: (CString)->Result
) -> Result {
@@ -104,9 +104,9 @@ extension String {
}
}
/// \brief Invoke f on the contents of this string, represented as
/// Invoke `f` on the contents of this string, represented as
/// a nul-terminated array of char, ensuring that the array's
/// lifetime extends through the execution of f
/// lifetime extends through the execution of `f`.
func withCString<Result>(
f: (UnsafePointer<CChar>)->Result
) -> Result {

6
stdlib/core/StaticString.swift
View File

@@ -10,15 +10,15 @@
//
//===----------------------------------------------------------------------===//
/// \brief An extremely simple string designed to represent something
/// "statically knowable".
// Implementation Note: Because StaticString is used in the
// implementation of assert() and fatal(), we keep it extremely close
// to the bare metal. In particular, because we use only Builtin
// types, we are guaranteed that no assertions are involved in its
// construction. This feature is crucial for preventing infinite
// recursion even in non-asserting cases.
/// An extremely simple string designed to represent something
/// "statically knowable".
struct StaticString
: _BuiltinExtendedGraphemeClusterLiteralConvertible,
ExtendedGraphemeClusterLiteralConvertible,

4
stdlib/core/String.swift
View File

@@ -100,8 +100,8 @@ extension String : DebugPrintable {
}
extension String {
/// \brief return the number of code units occupied by this string
/// in the given encoding
/// Return the number of code units occupied by this string
/// in the given encoding.
func _encodedLength<Encoding: UnicodeCodec>(encoding: Encoding.Type) -> Int {
var codeUnitCount = 0
self._encode(

10
stdlib/core/StringBridge.swift
View File

@@ -14,16 +14,16 @@
// variables, allowing the core stdlib to remain decoupled from
// Foundation.
/// \brief Effectively a proxy for NSString that doesn't mention it by
/// Effectively a proxy for NSString that doesn't mention it by
/// name. NSString's conformance to this protocol is declared in
/// Foundation.
@class_protocol @objc protocol _CocoaString {}
/// \brief Loading Foundation initializes these function variables
/// Loading Foundation initializes these function variables
/// with useful values
/// \brief produces a _StringBuffer from a given subrange of a source
/// _CocoaString, having the given minimum capacity.
/// Produces a `_StringBuffer` from a given subrange of a source
/// `_CocoaString`, having the given minimum capacity.
var _cocoaStringToContiguous: (
source: _CocoaString, range: Range<Int>, minimumCapacity: Int
) -> _StringBuffer = _cocoaStringToContiguousNotInitialized
@@ -34,7 +34,7 @@ func _cocoaStringToContiguousNotInitialized(
_fatalError("_cocoaStringToContiguous not initialized")
}
/// \brief reads the entire contents of a _CocoaString into contiguous
/// Reads the entire contents of a _CocoaString into contiguous
/// storage of sufficient capacity.
var _cocoaStringReadAll: (
source: _CocoaString, destination: UnsafePointer<UTF16.CodeUnit>

12
stdlib/core/StringBuffer.swift
View File

@@ -108,12 +108,12 @@ struct _StringBuffer {
}
}
/// \brief a pointer to the start of this buffer's data area
/// a pointer to the start of this buffer's data area
var start: UnsafePointer<RawByte> {
return UnsafePointer(_storage.elementStorage)
}
/// \brief a past-the-end pointer for this buffer's stored data
/// a past-the-end pointer for this buffer's stored data
var usedEnd: UnsafePointer<RawByte> {
get {
return _storage.value.usedEnd
@@ -127,22 +127,22 @@ struct _StringBuffer {
return (usedEnd - start) >> elementShift
}
/// \brief a past-the-end pointer for this buffer's available storage
/// a past-the-end pointer for this buffer's available storage
var capacityEnd: UnsafePointer<RawByte> {
return start + _storage.value.byteCapacity
}
/// \brief The number of elements that can be stored in this buffer
/// The number of elements that can be stored in this buffer
var capacity: Int {
return _storage.value.byteCapacity >> elementShift
}
/// \brief 1 if the buffer stores UTF16; 0 otherwise
/// 1 if the buffer stores UTF16; 0 otherwise
var elementShift: Int {
return _storage.value.elementShift
}
/// \brief the number of bytes per element
/// the number of bytes per element
var elementWidth: Int {
return elementShift + 1
}

12
stdlib/core/StringLegacy.swift
View File

@@ -170,7 +170,7 @@ extension String {
func _isSpace() -> Bool { return _isAll({ $0.isSpace() }) }
}
/// \brief Represent a positive integer value in the given radix,
/// Represent a positive integer value in the given radix,
/// writing each ASCII character into stream. The value of `ten'
/// should be either "A" or "a", depending on whether you want upper-
/// or lower-case letters when radix > 10
@@ -290,7 +290,7 @@ extension String {
// Conversions from string to other types.
extension String {
/// \brief If the string represents an integer that fits into an Int, returns
/// If the string represents an integer that fits into an Int, returns
/// the corresponding integer.
func toInt() -> Int? {
var scalars = self.unicodeScalars
@@ -345,7 +345,7 @@ extension String {
}
extension String {
/// \brief Produce a substring of the given string from the given character
/// Produce a substring of the given string from the given character
/// index to the end of the string.
func _substr(start: Int) -> String {
var rng = unicodeScalars
@@ -356,7 +356,7 @@ extension String {
return rng[startIndex..rng.endIndex]
}
/// \brief Split the given string at the given delimiter character, returning
/// Split the given string at the given delimiter character, returning
/// the strings before and after that character (neither includes the character
/// found) and a boolean value indicating whether the delimiter was found.
func _splitFirst(delim: UnicodeScalar)
@@ -371,7 +371,7 @@ extension String {
return (self, "", false)
}
/// \brief Split the given string at the first character for which the given
/// Split the given string at the first character for which the given
/// predicate returns true. Returns the string before that character, the
/// character that matches, the string after that character, and a boolean value
/// indicating whether any character was found.
@@ -387,7 +387,7 @@ extension String {
return (self, "🎃", String(), false)
}
/// \brief Split the given string at each occurrence of a character for which
/// Split the given string at each occurrence of a character for which
/// the given predicate evaluates true, returning an array of strings that
/// before/between/after those delimiters.
func _splitIf(pred: (UnicodeScalar) -> Bool) -> String[] {

16
stdlib/core/Unmanaged.swift
View File

@@ -25,7 +25,9 @@ struct Unmanaged<T: AnyObject> {
///
/// This operation does not change reference counts.
///
/// \c let str: CFString = Unmanaged.fromOpaque(ptr).takeUnretainedValue()
/// ::
///
/// let str: CFString = Unmanaged.fromOpaque(ptr).takeUnretainedValue()
@transparent
static func fromOpaque(value: COpaquePointer) -> Unmanaged {
return Unmanaged(_private: reinterpretCast(value))
@@ -36,7 +38,9 @@ struct Unmanaged<T: AnyObject> {
///
/// This operation does not change reference counts.
///
/// \c let str: CFString = Unmanaged.fromOpaque(ptr).takeUnretainedValue()
/// ::
///
/// let str: CFString = Unmanaged.fromOpaque(ptr).takeUnretainedValue()
@transparent
func toOpaque() -> COpaquePointer {
return reinterpretCast(_value)
@@ -49,7 +53,9 @@ struct Unmanaged<T: AnyObject> {
/// does not know the ownership rules for, but you know that the
/// API expects you to pass the object at +1.
///
/// \c CFAutorelease(.passRetained(object))
/// ::
///
/// CFAutorelease(.passRetained(object))
@transparent
static func passRetained(value: T) -> Unmanaged {
return Unmanaged(_private: value).retain()
@@ -62,7 +68,9 @@ struct Unmanaged<T: AnyObject> {
/// does not know the ownership rules for, but you know that the
/// API expects you to pass the object at +0.
///
/// \c CFArraySetValueAtIndex(.passUnretained(array), i,
/// ::
///
/// CFArraySetValueAtIndex(.passUnretained(array), i,
/// .passUnretained(object))
@transparent
static func passUnretained(value: T) -> Unmanaged {

2
stdlib/core/UnsafePointer.swift
View File

@@ -18,7 +18,7 @@
/// to allocate and free memory appropriately.
///
/// For C pointers for which the pointed-to type cannot be represented
/// directly in Swift, the \c COpaquePointer will be used instead.
/// directly in Swift, the `COpaquePointer` will be used instead.
struct UnsafePointer<T> : BidirectionalIndex, Comparable, Hashable {
/// The underlying raw (untyped) pointer.
var value : Builtin.RawPointer

2
stdlib/objc/Foundation/Foundation.swift
View File

@@ -116,7 +116,7 @@ extension NSString {
//===----------------------------------------------------------------------===//
extension NSString : _CocoaString {}
/// \brief Sets variables in Swift's core stdlib that allow it to
/// Sets variables in Swift's core stdlib that allow it to
/// bridge Cocoa strings properly. Currently invoked by a HACK in
/// Misc.mm; a better mechanism may be needed.
@asmname("__swift_initializeCocoaStringBridge")

317
stdlib/objc/Foundation/NSStringAPI.swift
View File

File diff suppressed because it is too large Load Diff

8
stdlib/objc/ObjectiveC-BOOLchar.swift
View File

@@ -26,21 +26,19 @@ struct ObjCBool {
self.value = value
}
/// \brief Allow use in a Boolean context.
/// Allow use in a Boolean context.
func getLogicValue() -> Bool {
return value != 0
}
/// \brief Implicit conversion from C Boolean type to Swift Boolean
/// type.
/// Implicit conversion from C Boolean type to Swift Boolean type.
@conversion func __conversion() -> Bool {
return self.getLogicValue()
}
}
extension Bool {
/// \brief Implicit conversion from Swift Boolean type to
/// Objective-C Boolean type.
/// Implicit conversion from Swift Boolean type to Objective-C Boolean type.
@conversion func __conversion() -> ObjCBool {
return ObjCBool(self ? 1 : 0)
}

10
stdlib/objc/ObjectiveC.swift
View File

@@ -25,7 +25,7 @@ extension ObjCBool : Printable {
}
}
/// \brief The Objective-C SEL type.
/// The Objective-C SEL type.
///
/// The Objective-C SEL type is typically an opaque pointer. Swift
/// treats it as a distinct struct type, with operations to
@@ -35,19 +35,19 @@ extension ObjCBool : Printable {
struct Selector : StringLiteralConvertible {
var ptr : COpaquePointer
/// \brief Create a selector from a string.
/// Create a selector from a string.
init(_ str : String) {
ptr = str.withCString { sel_registerName($0).ptr }
}
/// \brief Construct a selector from a string literal.
/// Construct a selector from a string literal.
static func convertFromExtendedGraphemeClusterLiteral(
value: CString) -> Selector {
return convertFromStringLiteral(value)
}
/// \brief Construct a selector from a string literal.
/// Construct a selector from a string literal.
///
/// FIXME: Fast-path this in the compiler, so we don't end up with
/// the sel_registerName call at compile time.
@@ -77,7 +77,7 @@ extension Selector : Printable {
}
extension String {
/// \brief Construct the C string representation of an Objective-C selector.
/// Construct the C string representation of an Objective-C selector.
init(_sel: Selector) {
// FIXME: This misses the ASCII optimization.
self = String.fromCString(sel_getName(_sel))