[Gardening] De-RST TransparentAttr

docs/LibraryEvolution.rst

@@ -210,7 +210,7 @@ any future use of the function must take this into account.
 Although they are not a supported feature for arbitrary libraries at this time,
 public `transparent`_ functions are implicitly marked ``@inlinable``.
 
-.. _transparent: https://github.com/apple/swift/blob/master/docs/TransparentAttr.rst
+.. _transparent: https://github.com/apple/swift/blob/master/docs/TransparentAttr.md
 
 
 Restrictions on Inlinable Functions

docs/StandardLibraryProgrammersManual.md

@@ -180,7 +180,7 @@ let theBits = unsafeBitCast(&x, ...)
 
 Should only be used if necessary. This has the effect of forcing inlining to occur before any dataflow analyses take place. Unless you specifically need this behavior, use `@_inline(__always)` or some other mechanism. Its primary purpose is to force the compiler's static checks to peer into the body for diagnostic purposes.
 
-Use of this attribute imposes limitations on what can be in the body. For more details, refer to the [documentation](https://github.com/apple/swift/blob/master/docs/TransparentAttr.rst).
+Use of this attribute imposes limitations on what can be in the body. For more details, refer to the [documentation](https://github.com/apple/swift/blob/master/docs/TransparentAttr.md).
 
 #### `@unsafe_no_objc_tagged_pointer`
 

docs/TransparentAttr.md

@@ -0,0 +1,75 @@
+`@_transparent`
+=================
+
+Semantically, `@_transparent` means something like "treat this operation as
+if it were a primitive operation". The name is meant to imply that both the
+compiler and the compiled program will "see through" the operation to its
+implementation.
+
+This has several consequences:
+
+- Any calls to a function marked `@_transparent` MUST be inlined prior to
+  doing dataflow-related diagnostics, even under `-Onone`. This may be
+  necessary to *catch* dataflow errors.
+
+- Because of this, a `@_transparent` function is implicitly inlinable, in
+  that changing its implementation most likely will not affect callers in
+  existing compiled binaries.
+
+- Because of this, a public or `@usableFromInline` `@_transparent` function
+  MUST only reference public symbols, and MUST not be optimized based on
+  knowledge of the module it's in. [The former is caught by checks in Sema.]
+
+- Debug info SHOULD skip over the inlined operations when single-stepping
+  through the calling function.
+
+This is all that `@_transparent` means.
+
+
+When should you use `@_transparent`?
+--------------------------------------
+
+- Does the implementation of this function ever have to change? Then you can't
+  allow it to be inlined.
+
+- Does the implementation need to call private things---either true-`private`
+  functions, or `internal` functions that might go away in the next release?
+  Then you can't allow it to be inlined.
+
+- Is it okay if the function is *not* inlined? You'd just prefer that it were?
+  Then you should use `@inlinable`, rather than `@_transparent`. (If you
+  really need this, you can add `@inline(__always)` as well.)
+
+- Is it a problem if the function is inlined even under `-Onone`? Then you're
+  really in the previous case. Trust the compiler.
+
+- Is it a problem if you can't step through the function that's been inlined?
+  Then you don't want `@_transparent`; you just want `@inline(__always)`
+  (and probably `@inlinable` as well, for cross-module inlining).
+
+- Is it okay if the inlining happens after all the dataflow diagnostics? Then
+  you don't want `@_transparent`; you just want `@inline(__always)`.
+
+If you made it this far, it sounds like `@_transparent` is the right choice.
+
+
+Interaction with other annotations
+----------------------------------
+
+- As mentioned above, putting `@_transparent` on a function that is
+  `public` or `@usableFromInline` exposes its body to other modules. It is
+  not necessary to additionally include `@inlinable`.
+
+- Unlike `@inlinable`, however, `@_transparent` does not imply
+  `@usableFromInline`. It is possible to have functions marked
+  `@_transparent` that are only meant for use within the current module or
+  even the current file.
+
+
+Current implementation limitations
+----------------------------------
+
+- When compiling in non-single-frontend mode, no SIL is generated for any
+  functions but those in the primary file (for each frontend invocation),
+  including `@inline(__always)` and `@_transparent` functions, which means
+  they will not be inlined. This is semantically a bug. rdar://problem/15366167

docs/TransparentAttr.rst

@@ -1,79 +0,0 @@
-:orphan:
-
-``@_transparent``
-=================
-
-Semantically, ``@_transparent`` means something like "treat this operation as
-if it were a primitive operation". The name is meant to imply that both the
-compiler and the compiled program will "see through" the operation to its
-implementation.
-
-This has several consequences:
-
-- Any calls to a function marked ``@_transparent`` MUST be inlined prior to
-  doing dataflow-related diagnostics, even under ``-Onone``. This may be
-  necessary to *catch* dataflow errors.
-
-- Because of this, a ``@_transparent`` function is implicitly inlinable, in
-  that changing its implementation most likely will not affect callers in
-  existing compiled binaries.
-
-- Because of this, a public or ``@usableFromInline`` ``@_transparent`` function
-  MUST only reference public symbols, and MUST not be optimized based on
-  knowledge of the module it's in. [The former is caught by checks in Sema.]
-
-- Debug info SHOULD skip over the inlined operations when single-stepping
-  through the calling function.
-
-This is all that ``@_transparent`` means.
-
-
-.. _transparent-attribute:
-
-When should you use ``@_transparent``?
---------------------------------------
-
-- Does the implementation of this function ever have to change? Then you can't
-  allow it to be inlined.
-
-- Does the implementation need to call private things---either true-``private``
-  functions, or ``internal`` functions that might go away in the next release?
-  Then you can't allow it to be inlined.
-
-- Is it okay if the function is *not* inlined? You'd just prefer that it were?
-  Then you should use ``@inlinable``, rather than ``@_transparent``. (If you
-  really need this, you can add ``@inline(__always)`` as well.)
-
-- Is it a problem if the function is inlined even under ``-Onone``? Then you're
-  really in the previous case. Trust the compiler.
-
-- Is it a problem if you can't step through the function that's been inlined?
-  Then you don't want ``@_transparent``; you just want ``@inline(__always)``
-  (and probably ``@inlinable`` as well, for cross-module inlining).
-
-- Is it okay if the inlining happens after all the dataflow diagnostics? Then
-  you don't want ``@_transparent``; you just want ``@inline(__always)``.
-
-If you made it this far, it sounds like ``@_transparent`` is the right choice.
-
-
-Interaction with other annotations
-----------------------------------
-
-- As mentioned above, putting ``@_transparent`` on a function that is
-  ``public`` or ``@usableFromInline`` exposes its body to other modules. It is
-  not necessary to additionally include ``@inlinable``.
-
-- Unlike ``@inlinable``, however, ``@_transparent`` does not imply
-  ``@usableFromInline``. It is possible to have functions marked
-  ``@_transparent`` that are only meant for use within the current module or
-  even the current file.
-
-
-Current implementation limitations
-----------------------------------
-
-- When compiling in non-single-frontend mode, no SIL is generated for any
-  functions but those in the primary file (for each frontend invocation),
-  including ``@inline(__always)`` and ``@_transparent`` functions, which means
-  they will not be inlined. This is semantically a bug. rdar://problem/15366167