Add more miscellaneous YARD docs (faker-ruby#1756)

* Add YARD docs for Faker::Nation.

* Add YARD docs for One Piece.

* Add YARD docs for The Big Lebowski.

* Add YARD docs for Star Wars.

* Add YARD docs for HarryPotter.

* Add YARD docs for Back to the Future.

* Add YARD docs for Ghostbusters.

* Add YARD docs for Lord of the Rings.

* Add YARD docs for The Princess Bride.

* Add YARD docs for V For Vendetta.

* Fixes to appease rubocop.

* Add YARD docs for Hitchhiker's Guide to the Galaxy.

* Fix missing double-hashes at the start of doc blocks.

* Fix it for One Piece as well.

lib/faker/default/nation.rb

@@ -4,27 +4,70 @@ module Faker
   class Nation < Base
     flexible :nation
     class << self
-      # Fetch random nationality
+      ##
+      # Produces a random nationality.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.nationality #=> "Nepalese"
+      #
+      # @faker.version 1.9.0
       def nationality
         fetch('nation.nationality')
       end
 
-      # Fetch random national flag emoji
+      # rubocop:disable Style/AsciiComments
+
+      ##
+      # Produces a random national flag emoji.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.flag #=> "🇫🇮"
+      #
+      # @faker.version 1.9.0
       def flag
         sample(translate('faker.nation.flag')).pack('C*').force_encoding('utf-8')
       end
+      # rubocop:enable Style/AsciiComments
 
-      # Fetch random language
+      ##
+      # Produces a random national language.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.language #=> "Nepali"
+      #
+      # @faker.version 1.9.0
       def language
         fetch('nation.language')
       end
 
-      # Fetch random capital city
+      ##
+      # Produces a random capital city.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.capital_city #=> "Kathmandu"
+      #
+      # @faker.version 1.9.0
       def capital_city
         fetch('nation.capital_city')
       end
 
-      # Fetch random natinal sport
+      ##
+      # Produces a random national sport.
+      #
+      # @return [String]
+      #
+      # @example
+      #   Faker::Nation.national_sport #=> "dandi biyo"
+      #
+      # @faker.version 1.9.0
       def national_sport
         fetch('team.sport')
       end

lib/faker/japanese_media/one_piece.rb

@@ -4,26 +4,80 @@ module Faker
   class JapaneseMedia
     class OnePiece < Base
       class << self
+        ##
+        # Produces a character from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.character #=> "Monkey D. Luffy"
+        #
+        # @faker.version 1.8.5
         def character
           fetch('one_piece.characters')
         end
 
+        ##
+        # Produces a sea from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.sea #=> "East Blue"
+        #
+        # @faker.version 1.8.5
         def sea
           fetch('one_piece.seas')
         end
 
+        ##
+        # Produces an island from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.island #=> "Laftel"
+        #
+        # @faker.version 1.8.5
         def island
           fetch('one_piece.islands')
         end
 
+        ##
+        # Produces a location from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.location #=> "Foosha Village"
+        #
+        # @faker.version 1.8.5
         def location
           fetch('one_piece.locations')
         end
 
+        ##
+        # Produces a quote from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.quote #=> "ONE PIECE IS REAL!"
+        #
+        # @faker.version 1.8.5
         def quote
           fetch('one_piece.quotes')
         end
 
+        ##
+        # Produces an akuma no mi from One Piece.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::JapaneseMedia::OnePiece.akuma_no_mi #=> "Gomu Gomu no Mi"
+        #
+        # @faker.version 1.8.5
         def akuma_no_mi
           fetch('one_piece.akumas_no_mi')
         end

lib/faker/movies/back_to_the_future.rb

@@ -4,14 +4,42 @@ module Faker
   class Movies
     class BackToTheFuture < Base
       class << self
+        ##
+        # Produces a character from Back to the Future.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::BackToTheFuture.character #=> "Marty McFly"
+        #
+        # @faker.version 1.8.5
         def character
           fetch('back_to_the_future.characters')
         end
 
+        ##
+        # Produces a date from Back to the Future.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::BackToTheFuture.date #=> "November 5, 1955"
+        #
+        # @faker.version 1.8.5
         def date
           fetch('back_to_the_future.dates')
         end
 
+        ##
+        # Produces a quote from Back to the Future.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::BackToTheFuture.quote
+        #     #=> "Roads? Where we're going, we don't need roads."
+        #
+        # @faker.version 1.8.5
         def quote
           fetch('back_to_the_future.quotes')
         end

lib/faker/movies/ghostbusters.rb

@@ -4,14 +4,42 @@ module Faker
   class Movies
     class Ghostbusters < Base
       class << self
+        ##
+        # Produces an actor from Ghostbusters.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::Ghostbusters.actor #=> "Bill Murray"
+        #
+        # @faker.version 1.9.2
         def actor
           fetch('ghostbusters.actors')
         end
 
+        ##
+        # Produces a character from Ghostbusters.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::Ghostbusters.character #=> "Dr. Egon Spengler"
+        #
+        # @faker.version 1.9.2
         def character
           fetch('ghostbusters.characters')
         end
 
+        ##
+        # Produces a quote from Ghostbusters.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::Ghostbusters.quote
+        #     #=> "I tried to think of the most harmless thing. Something I loved from my childhood. Something that could never ever possibly destroy us. Mr. Stay Puft!"
+        #
+        # @faker.version 1.9.2
         def quote
           fetch('ghostbusters.quotes')
         end

lib/faker/movies/harry_potter.rb

@@ -4,26 +4,80 @@ module Faker
   class Movies
     class HarryPotter < Base
       class << self
+        ##
+        # Produces a character from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.character #=> "Harry Potter"
+        #
+        # @faker.version 1.7.3
         def character
           fetch('harry_potter.characters')
         end
 
+        ##
+        # Produces a location from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.location #=> "Hogwarts"
+        #
+        # @faker.version 1.7.3
         def location
           fetch('harry_potter.locations')
         end
 
+        ##
+        # Produces a quote from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.quote #=> "I solemnly swear that I am up to good."
+        #
+        # @faker.version 1.7.3
         def quote
           fetch('harry_potter.quotes')
         end
 
+        ##
+        # Produces a book from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.book #=> "Harry Potter and the Chamber of Secrets"
+        #
+        # @faker.version 1.7.3
         def book
           fetch('harry_potter.books')
         end
 
+        ##
+        # Produces a house from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.house #=> "Gryffindor"
+        #
+        # @faker.version 1.7.3
         def house
           fetch('harry_potter.houses')
         end
 
+        ##
+        # Produces a spell from Harry Potter.
+        #
+        # @return [String]
+        #
+        # @example
+        #   Faker::Movies::HarryPotter.spell #=> "Reparo"
+        #
+        # @faker.version 1.7.3
         def spell
           fetch('harry_potter.spells')
         end