Merge pull request #119 from amartini51/doc_comment_placement

Fix doc comment placement

Author: amartini51

Sources/System/FilePath/FilePath.swift

@@ -7,6 +7,9 @@
  See https://swift.org/LICENSE.txt for license information
 */
 
+// TODO(docs): Section on all the new syntactic operations, lexical normalization, decomposition,
+// components, etc.
+/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 /// Represents a location in the file system.
 ///
 /// This structure recognizes directory separators  (e.g. `/`), roots, and
@@ -37,10 +40,6 @@
 /// However, the rules for path equivalence
 /// are file-system–specific and have additional considerations
 /// like case insensitivity, Unicode normalization, and symbolic links.
-///
-// TODO(docs): Section on all the new syntactic operations, lexical normalization, decomposition,
-// components, etc.
-/*System 0.0.1, @available(macOS 11.0, iOS 14.0, watchOS 7.0, tvOS 14.0, *)*/
 public struct FilePath {
   internal var _storage: SystemString
 

Sources/System/FilePath/FilePathComponentView.swift

@@ -28,7 +28,6 @@ extension FilePath {
   ///
   ///     path.components.removeAll { $0.kind == .currentDirectory }
   ///     // path is "/home/username/bin/scripts/tree"
-  ///
   public struct ComponentView {
     internal var _path: FilePath
     internal var _start: SystemString.Index

Sources/System/FilePath/FilePathComponents.swift

@@ -54,7 +54,6 @@ extension FilePath {
   ///     file.kind == .regular           // true
   ///     file.extension                  // "txt"
   ///     path.append(file)               // path is "/tmp/foo.txt"
-  ///
   public struct Component {
     internal var _path: FilePath
     internal var _range: Range<SystemString.Index>

Sources/System/FilePath/FilePathString.swift

@@ -98,7 +98,6 @@ extension FilePath.Component {
   ///
   /// - Parameter platformString: A pointer to a null-terminated platform
   ///   string.
-  ///
   public init?(platformString: UnsafePointer<CInterop.PlatformChar>) {
     self.init(_platformString: platformString)
   }
@@ -187,7 +186,6 @@ extension FilePath.Root {
   ///
   /// - Parameter platformString: A pointer to a null-terminated platform
   ///   string.
-  ///
   public init?(platformString: UnsafePointer<CInterop.PlatformChar>) {
     self.init(_platformString: platformString)
   }

Sources/System/FilePath/FilePathSyntax.swift

@@ -52,6 +52,8 @@ extension FilePath {
   ///   * `\Users`
   public var isRelative: Bool { !isAbsolute }
 
+  // TODO(Windows docs): examples with roots, such as whether `\foo\bar`
+  //   starts with `C:\foo`
   /// Returns whether `other` is a prefix of `self`, only considering
   /// whole path components.
   ///
@@ -63,15 +65,14 @@ extension FilePath {
   ///     path.starts(with: "/usr/bin/ls")    // true
   ///     path.starts(with: "/usr/bin/ls///") // true
   ///     path.starts(with: "/us")            // false
-  ///
-  // TODO(Windows docs): examples with roots, such as whether `\foo\bar`
-  //   starts with `C:\foo`
   public func starts(with other: FilePath) -> Bool {
     guard !other.isEmpty else { return true }
     return self.root == other.root && components.starts(
       with: other.components)
   }
 
+  // TODO(Windows docs): examples with roots, such as whether `C:\foo\bar`
+  //   ends with `C:bar`
   /// Returns whether `other` is a suffix of `self`, only considering
   /// whole path components.
   ///
@@ -83,9 +84,6 @@ extension FilePath {
   ///     path.ends(with: "usr/bin/ls")     // true
   ///     path.ends(with: "/usr/bin/ls///") // true
   ///     path.ends(with: "/ls")            // false
-  ///
-  // TODO(Windows docs): examples with roots, such as whether `C:\foo\bar`
-  //   ends with `C:bar`
   public func ends(with other: FilePath) -> Bool {
     if other.root != nil {
       // TODO: anything tricky here for Windows?
@@ -145,7 +143,6 @@ extension FilePath {
   ///     path.root = nil         // path is #"foo\bar"#
   ///     path.root = "C:"        // path is #"C:foo\bar"#
   ///     path.root = #"C:\"#     // path is #"C:\foo\bar"#
-  ///
   public var root: FilePath.Root? {
     get {
       guard _hasRoot else { return nil }
@@ -178,7 +175,6 @@ extension FilePath {
   ///   * `\\?\device\folder\file.exe  => folder\file.exe`
   ///   * `\\server\share\file         => file`
   ///   * `\                           => ""`
-  ///
   public __consuming func removingRoot() -> FilePath {
     var copy = self
     copy.root = nil
@@ -209,7 +205,6 @@ extension FilePath {
   ///   * `\\?\UNC\server\share\bar.exe => bar.exe`
   ///   * `\\server\share               => nil`
   ///   * `\\?\UNC\server\share\        => nil`
-  ///
   public var lastComponent: Component? { components.last }
 
   /// Creates a new path with everything up to but not including
@@ -247,7 +242,6 @@ extension FilePath {
   ///     path.removeLastComponent() == true  // path is "/usr"
   ///     path.removeLastComponent() == true  // path is "/"
   ///     path.removeLastComponent() == false // path is "/"
-  ///
   @discardableResult
   public mutating func removeLastComponent() -> Bool {
     defer { _invariantCheck() }
@@ -271,7 +265,6 @@ extension FilePath.Component {
   ///   * `Foo.app    => app`
   ///   * `.hidden    => nil`
   ///   * `..         => nil`
-  ///
   public var `extension`: String? {
     guard let range = _extensionRange() else { return nil }
     return _slice[range].string
@@ -285,7 +278,6 @@ extension FilePath.Component {
   ///   * `Foo.app => Foo`
   ///   * `.hidden => .hidden`
   ///   * `..      => ..`
-  ///
   public var stem: String {
     _slice[_stemRange()].string
   }
@@ -322,7 +314,6 @@ extension FilePath {
   ///     path.extension = "o"   // path is "/tmp/file.o"
   ///     path.extension = nil    // path is "/tmp/file"
   ///     path.extension = ""     // path is "/tmp/file."
-  ///
   public var `extension`: String? {
     get { lastComponent?.extension }
     set {
@@ -441,6 +432,7 @@ extension FilePath {
 // Modification and concatenation API
 /*System 0.0.2, @available(macOS 12.0, iOS 15.0, watchOS 8.0, tvOS 15.0, *)*/
 extension FilePath {
+  // TODO(Windows docs): example with roots
   /// If `prefix` is a prefix of `self`, removes it and returns `true`.
   /// Otherwise returns `false`.
   ///
@@ -450,8 +442,6 @@ extension FilePath {
   ///     path.removePrefix("/usr/bin")   // false
   ///     path.removePrefix("/us")        // false
   ///     path.removePrefix("/usr/local") // true, path is "bin"
-  ///
-  // TODO(Windows docs): example with roots
   public mutating func removePrefix(_ prefix: FilePath) -> Bool {
     defer { _invariantCheck() }
     // FIXME: Should Windows have more nuanced semantics?
@@ -462,6 +452,7 @@ extension FilePath {
     return true
   }
 
+  // TODO(Windows docs): example with roots
   /// Append a `component` on to the end of this path.
   ///
   /// Example:
@@ -472,13 +463,12 @@ extension FilePath {
   ///       path.append(comp)
   ///     }
   ///     // path is "/tmp/foo/bar/../baz"
-  ///
-  // TODO(Windows docs): example with roots
   public mutating func append(_ component: __owned FilePath.Component) {
     defer { _invariantCheck() }
     _append(unchecked: component._slice)
   }
 
+  // TODO(Windows docs): example with roots
   /// Append `components` on to the end of this path.
   ///
   /// Example:
@@ -487,8 +477,6 @@ extension FilePath {
   ///     path.append(["usr", "local"])     // path is "/usr/local"
   ///     let otherPath: FilePath = "/bin/ls"
   ///     path.append(otherPath.components) // path is "/usr/local/bin/ls"
-  ///
-  // TODO(Windows docs): example with roots
   public mutating func append<C: Collection>(
     _ components: __owned C
   ) where C.Element == FilePath.Component {
@@ -498,6 +486,8 @@ extension FilePath {
     }
   }
 
+  // TODO(Windows docs): example with roots, should we rephrase this "spurious
+  // roots"?
   /// Append the contents of `other`, ignoring any spurious leading separators.
   ///
   /// A leading separator is spurious if `self` is non-empty.
@@ -508,9 +498,6 @@ extension FilePath {
   ///     path.append("/var/www/website") // "/var/www/website"
   ///     path.append("static/assets") // "/var/www/website/static/assets"
   ///     path.append("/main.css") // "/var/www/website/static/assets/main.css"
-  ///
-  // TODO(Windows docs): example with roots, should we rephrase this "spurious
-  // roots"?
   public mutating func append(_ other: __owned String) {
     defer { _invariantCheck() }
     guard !other.utf8.isEmpty else { return }
@@ -522,18 +509,16 @@ extension FilePath {
     _append(unchecked: otherPath._storage[otherPath._relativeStart...])
   }
 
-  /// Non-mutating version of `append(_:Component)`.
-  ///
   // TODO(Windows docs): example with roots
+  /// Non-mutating version of `append(_:Component)`.
   public __consuming func appending(_ other: __owned Component) -> FilePath {
     var copy = self
     copy.append(other)
     return copy
   }
 
-  /// Non-mutating version of `append(_:C)`.
-  ///
   // TODO(Windows docs): example with roots
+  /// Non-mutating version of `append(_:C)`.
   public __consuming func appending<C: Collection>(
     _ components: __owned C
   ) -> FilePath where C.Element == FilePath.Component {
@@ -542,15 +527,16 @@ extension FilePath {
     return copy
   }
 
-  /// Non-mutating version of `append(_:String)`.
-  ///
   // TODO(Windows docs): example with roots
+  /// Non-mutating version of `append(_:String)`.
   public __consuming func appending(_ other: __owned String) -> FilePath {
     var copy = self
     copy.append(other)
     return copy
   }
 
+  // TODO(Windows docs): examples and docs with roots, update/generalize doc
+  // comment
   /// If `other` does not have a root, append each component of `other`. If
   /// `other` has a root, replaces `self` with other.
   ///
@@ -564,9 +550,6 @@ extension FilePath {
   ///     var path: FilePath = "/tmp"
   ///     path.push("dir/file.txt") // path is "/tmp/dir/file.txt"
   ///     path.push("/bin")         // path is "/bin"
-  ///
-  // TODO(Windows docs): examples and docs with roots, update/generalize doc
-  // comment
   public mutating func push(_ other: __owned FilePath) {
     defer { _invariantCheck() }
     guard other.root == nil else {
@@ -577,9 +560,8 @@ extension FilePath {
     _append(unchecked: other._storage[...])
   }
 
-  /// Non-mutating version of `push()`.
-  ///
   // TODO(Windows docs): examples and docs with roots
+  /// Non-mutating version of `push()`.
   public __consuming func pushing(_ other: __owned FilePath) -> FilePath {
     var copy = self
     copy.push(other)

Sources/System/FilePath/FilePathWindows.swift

@@ -150,21 +150,19 @@ internal struct WindowsRootInfo {
     /// * Omitted volume from other forms: `\\.\`, `\\.\UNC\server\\`, `\\server\\`
     case empty
 
+    // TODO: NT paths? Admin paths using `$`?
     /// A specified drive.
     ///
     /// * Traditional disk: `C:\`, `C:`
     /// * Device disk: `\\.\C:\`, `\\?\C:\`
     /// * UNC: `\\server\e:\`, `\\?\UNC\server\e:\`
-    ///
-    // TODO: NT paths? Admin paths using `$`?
     case drive(Character)
 
+    // TODO: GUID type?
     /// A volume with a GUID in a non-traditional path
     ///
     /// * UNC: `\\host\Volume{0000-...}\`, `\\.\UNC\host\Volume{0000-...}\`
     /// * Device roots: `\\.\Volume{0000-...}\`, `\\?\Volume{000-...}\`
-    ///
-    // TODO: GUID type?
     case guid(String)
 
     // TODO: Legacy DOS devices, such as COM1?

Tests/SystemTests/FilePathTests/FilePathExtras.swift

@@ -51,7 +51,6 @@ extension FilePath {
 
   /// Whether a lexically-normalized `self` contains a lexically-normalized
   /// `other`.
-  ///
   public func lexicallyContains(_ other: FilePath) -> Bool {
     guard !other.isEmpty else { return true }
     guard !isEmpty else { return false }