Add YARD docs to Faker::File (#1990)

Co-authored-by: Daniel Tiringer <daniel@t530>

lib/faker/default/file.rb

@@ -3,6 +3,21 @@
 module Faker
   class File < Base
     class << self
+      ##
+      # Produces a random directory name.
+      #
+      # @param segment_count [Integer] Specifies the number of nested folders in the generated string.
+      # @param root [String] Specifies the root of the generated string.
+      # @param directory_separator [String] Specifies the separator between the segments.
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.dir #=> "et_error/sint_voluptas/quas_veritatis"
+      #   Faker::File.dir(segment_count: 2) #=> "ea-suscipit/ut-deleniti"
+      #   Faker::File.dir(segment_count: 3, root: nil, directory_separator: '/') #=> "est_porro/fugit_eveniet/incidunt-autem"
+      #   Faker::File.dir(segment_count: 3, root: nil, directory_separator: '\\') #=> "aut-ullam\\quia_quisquam\\ut-eos"
+      #
+      # @faker.version 1.6.4
       # rubocop:disable Metrics/ParameterLists
       def dir(legacy_segment_count = NOT_GIVEN, legacy_root = NOT_GIVEN, legacy_directory_separator = NOT_GIVEN, segment_count: 3, root: nil, directory_separator: ::File::Separator)
         # rubocop:enable Metrics/ParameterLists
@@ -20,14 +35,48 @@ def dir(legacy_segment_count = NOT_GIVEN, legacy_root = NOT_GIVEN, legacy_direct
           .squeeze(directory_separator)
       end
 
+      ##
+      # Produces a random file extension.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.extension #=> "mp3"
+      #
+      # @faker.version 1.6.4
       def extension
         fetch('file.extension')
       end
 
+      ##
+      # Produces a random mime type.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.mime_type #=> "application/pdf"
+      #
+      # @faker.version 1.6.4
       def mime_type
         fetch('file.mime_type')
       end
 
+      ##
+      # Produces a random file name.
+      #
+      # @param dir [String] Specifies the path used for the generated file.
+      # @param name [String] Specifies the filename used for the generated file.
+      # @param extension [String] Specifies the extension used the generated file.
+      # @param directory_separator [String] Specifies the separator between the directory and name elements.
+      # @return [String]
+      #
+      # @example
+      #   Faker::File.file_name(dir: 'path/to') #=> "path/to/something_random.jpg"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz') #=> "foo/bar/baz.zip"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz', ext: 'doc') #=> "foo/bar/baz.doc"
+      #   Faker::File.file_name(dir: 'foo/bar', name: 'baz', ext: 'mp3', directory_separator: '\\') #=> "foo/bar\\baz.mp3"
+      #
+      # @faker.version 1.6.4
       # rubocop:disable Metrics/ParameterLists
       def file_name(legacy_dir = NOT_GIVEN, legacy_name = NOT_GIVEN, legacy_ext = NOT_GIVEN, legacy_directory_separator = NOT_GIVEN, dir: nil, name: nil, ext: nil, directory_separator: ::File::Separator)
         # rubocop:enable Metrics/ParameterLists