Add version in API Docs

[steelcityamir]

I've been using FakerJS for a few months now and have noticed that a new feature will be added to the docs that is not yet in the latest release.

It would be helpful for developers to include a "supported version" tag beside each API method.

Example:
faker.company.name() is listed in the docs but is not in version 7.3.0 (latest release)
https://fakerjs.dev/api/company.html#name

[ST-DDT]

I created an issue for that: #1245

[matthewmayer]

As discussed on #1245 potentially could add a @since tag to each method to achieve this

I wrote a little script to check what the first version of faker which supported each current method in 7.4.0:

faker.definitions,1.0.0
faker.fake,3.0.0
faker.unique,5.0.0
faker.mersenne,5.5.0
faker.mersenne.gen,6.0.0
faker.mersenne.rand,5.5.0
faker.mersenne.seed,5.5.0
faker.mersenne.seed_array,5.5.0
faker.random,1.0.0
faker.random.faker,6.0.0
faker.random.word,3.1.0
faker.random.words,3.1.0
faker.random.locale,3.1.0
faker.random.alpha,5.0.0
faker.random.alphaNumeric,3.1.0
faker.random.numeric,6.3.0
faker.helpers,2.0.1
faker.helpers.faker,6.0.0
faker.helpers.slugify,2.0.1
faker.helpers.replaceSymbolWithNumber,2.0.1
faker.helpers.replaceSymbols,3.0.0
faker.helpers.replaceCreditCardSymbols,5.0.0
faker.helpers.repeatString,5.0.0
faker.helpers.regexpStyleStringParse,5.0.0
faker.helpers.shuffle,2.0.1
faker.helpers.uniqueArray,6.0.0
faker.helpers.mustache,2.0.1
faker.helpers.maybe,6.3.0
faker.helpers.objectKey,6.3.0
faker.helpers.objectValue,6.3.0
faker.helpers.arrayElement,6.3.0
faker.helpers.arrayElements,6.3.0
faker.helpers.fake,7.4.0
faker.datatype,5.5.0
faker.datatype.faker,6.0.0
faker.datatype.number,5.5.0
faker.datatype.float,5.5.0
faker.datatype.datetime,5.5.0
faker.datatype.string,5.5.0
faker.datatype.uuid,5.5.0
faker.datatype.boolean,5.5.0
faker.datatype.hexadecimal,6.1.2
faker.datatype.json,5.5.0
faker.datatype.array,5.5.0
faker.datatype.bigInt,6.0.0
faker.address,2.0.1
faker.address.faker,6.0.0
faker.address.zipCode,2.0.1
faker.address.zipCodeByState,5.0.0
faker.address.city,2.0.1
faker.address.cityPrefix,2.0.1
faker.address.citySuffix,2.0.1
faker.address.cityName,5.5.0
faker.address.buildingNumber,6.2.0
faker.address.street,7.0.0
faker.address.streetName,2.0.1
faker.address.streetAddress,2.0.1
faker.address.streetSuffix,2.0.1
faker.address.streetPrefix,3.0.0
faker.address.secondaryAddress,2.0.1
faker.address.county,2.0.1
faker.address.country,2.0.1
faker.address.countryCode,3.0.0
faker.address.state,2.0.1
faker.address.stateAbbr,2.0.1
faker.address.latitude,2.0.1
faker.address.longitude,2.0.1
faker.address.direction,5.0.0
faker.address.cardinalDirection,5.0.0
faker.address.ordinalDirection,5.0.0
faker.address.nearbyGPSCoordinate,5.0.0
faker.address.timeZone,5.1.0
faker.animal,5.5.0
faker.animal.faker,6.0.0
faker.animal.dog,5.5.0
faker.animal.cat,5.5.0
faker.animal.snake,5.5.0
faker.animal.bear,5.5.0
faker.animal.lion,5.5.0
faker.animal.cetacean,5.5.0
faker.animal.horse,5.5.0
faker.animal.bird,5.5.0
faker.animal.cow,5.5.0
faker.animal.fish,5.5.0
faker.animal.crocodilia,5.5.0
faker.animal.insect,5.5.0
faker.animal.rabbit,5.5.0
faker.animal.rodent,7.4.0
faker.animal.type,5.5.0
faker.color,7.0.0
faker.color.faker,7.0.0
faker.color.human,7.0.0
faker.color.space,7.0.0
faker.color.cssSupportedFunction,7.0.0
faker.color.cssSupportedSpace,7.0.0
faker.color.rgb,7.0.0
faker.color.cmyk,7.0.0
faker.color.hsl,7.0.0
faker.color.hwb,7.0.0
faker.color.lab,7.0.0
faker.color.lch,7.0.0
faker.color.colorByCSSColorSpace,7.0.0
faker.commerce,3.0.0
faker.commerce.faker,6.0.0
faker.commerce.color,3.0.0
faker.commerce.department,3.0.0
faker.commerce.productName,3.0.0
faker.commerce.price,3.0.0
faker.commerce.productAdjective,3.0.0
faker.commerce.productMaterial,3.0.0
faker.commerce.product,3.0.0
faker.commerce.productDescription,5.0.0
faker.company,2.0.1
faker.company.faker,6.0.0
faker.company.suffixes,2.0.1
faker.company.name,7.4.0
faker.company.companyName,2.0.1
faker.company.companySuffix,2.0.1
faker.company.catchPhrase,2.0.1
faker.company.bs,2.0.1
faker.company.catchPhraseAdjective,2.0.1
faker.company.catchPhraseDescriptor,2.0.1
faker.company.catchPhraseNoun,2.0.1
faker.company.bsAdjective,2.0.1
faker.company.bsBuzz,2.0.1
faker.company.bsNoun,2.0.1
faker.database,4.0.0
faker.database.faker,6.0.0
faker.database.column,4.0.0
faker.database.type,4.0.0
faker.database.collation,4.0.0
faker.database.engine,4.0.0
faker.database.mongodbObjectId,6.2.0
faker.date,2.0.1
faker.date.faker,6.0.0
faker.date.past,2.0.1
faker.date.future,2.0.1
faker.date.between,2.0.1
faker.date.betweens,5.4.0
faker.date.recent,2.0.1
faker.date.soon,5.0.0
faker.date.month,3.0.1
faker.date.weekday,3.0.1
faker.date.birthdate,7.0.0
faker.finance,2.0.1
faker.finance.faker,6.0.0
faker.finance.account,2.0.1
faker.finance.accountName,2.0.1
faker.finance.routingNumber,5.0.0
faker.finance.mask,2.0.1
faker.finance.amount,2.0.1
faker.finance.transactionType,2.0.1
faker.finance.currencyCode,2.0.1
faker.finance.currencyName,2.0.1
faker.finance.currencySymbol,2.0.1
faker.finance.bitcoinAddress,3.1.0
faker.finance.litecoinAddress,5.0.0
faker.finance.creditCardNumber,5.0.0
faker.finance.creditCardCVV,5.0.0
faker.finance.creditCardIssuer,6.3.0
faker.finance.pin,6.2.0
faker.finance.ethereumAddress,5.0.0
faker.finance.iban,4.0.0
faker.finance.bic,4.0.0
faker.finance.transactionDescription,5.1.0
faker.git,5.0.0
faker.git.faker,6.0.0
faker.git.hexChars,6.0.0
faker.git.branch,5.0.0
faker.git.commitEntry,5.0.0
faker.git.commitMessage,5.0.0
faker.git.commitSha,5.0.0
faker.git.shortSha,5.0.0
faker.hacker,2.0.1
faker.hacker.faker,6.0.0
faker.hacker.abbreviation,2.0.1
faker.hacker.adjective,2.0.1
faker.hacker.noun,2.0.1
faker.hacker.verb,2.0.1
faker.hacker.ingverb,2.0.1
faker.hacker.phrase,2.0.1
faker.image,2.0.1
faker.image.faker,6.0.0
faker.image.image,2.0.1
faker.image.avatar,2.0.1
faker.image.imageUrl,2.0.1
faker.image.abstract,2.0.1
faker.image.animals,2.0.1
faker.image.business,2.0.1
faker.image.cats,2.0.1
faker.image.city,2.0.1
faker.image.food,2.0.1
faker.image.nightlife,2.0.1
faker.image.fashion,2.0.1
faker.image.people,2.0.1
faker.image.nature,2.0.1
faker.image.sports,2.0.1
faker.image.technics,2.0.1
faker.image.transport,2.0.1
faker.image.dataUri,4.0.0
faker.image.lorempixel,5.0.0
faker.image.unsplash,5.0.0
faker.image.lorempicsum,5.1.0
faker.image.placeholder,7.4.0
faker.internet,2.0.1
faker.internet.faker,6.0.0
faker.internet.avatar,2.0.1
faker.internet.email,2.0.1
faker.internet.exampleEmail,3.1.0
faker.internet.userName,2.0.1
faker.internet.protocol,2.1.5
faker.internet.httpMethod,5.4.0
faker.internet.httpStatusCode,7.0.0
faker.internet.url,2.1.5
faker.internet.domainName,2.0.1
faker.internet.domainSuffix,2.0.1
faker.internet.domainWord,2.0.1
faker.internet.ip,2.0.1
faker.internet.ipv4,6.1.1
faker.internet.ipv6,4.0.0
faker.internet.port,5.4.0
faker.internet.userAgent,2.0.1
faker.internet.color,2.0.1
faker.internet.mac,3.0.0
faker.internet.password,2.0.1
faker.internet.emoji,6.2.0
faker.lorem,2.0.1
faker.lorem.faker,6.0.0
faker.lorem.word,3.1.0
faker.lorem.words,2.0.1
faker.lorem.sentence,2.0.1
faker.lorem.slug,4.0.0
faker.lorem.sentences,2.0.1
faker.lorem.paragraph,2.0.1
faker.lorem.paragraphs,2.0.1
faker.lorem.text,3.1.0
faker.lorem.lines,3.1.0
faker.music,5.2.0
faker.music.faker,6.0.0
faker.music.genre,5.2.0
faker.music.songName,7.1.0
faker.name,2.0.1
faker.name.faker,6.0.0
faker.name.firstName,2.0.1
faker.name.lastName,2.0.1
faker.name.middleName,5.2.0
faker.name.findName,2.0.1
faker.name.fullName,7.4.0
faker.name.gender,5.0.0
faker.name.prefix,2.0.1
faker.name.suffix,2.0.1
faker.name.jobTitle,3.0.0
faker.name.jobDescriptor,3.0.0
faker.name.jobArea,3.0.0
faker.name.jobType,3.0.0
faker.phone,2.0.1
faker.phone.faker,6.0.0
faker.phone.phoneNumber,2.0.1
faker.phone.number,7.3.0
faker.phone.phoneNumberFormat,2.0.1
faker.phone.phoneFormats,2.0.1
faker.phone.imei,6.2.0
faker.science,7.2.0
faker.science.faker,7.2.0
faker.science.chemicalElement,7.2.0
faker.science.unit,7.2.0
faker.system,3.1.0
faker.system.faker,6.0.0
faker.system.fileName,3.1.0
faker.system.commonFileName,3.1.0
faker.system.mimeType,3.1.0
faker.system.commonFileType,3.1.0
faker.system.commonFileExt,3.1.0
faker.system.fileType,3.1.0
faker.system.fileExt,3.1.0
faker.system.directoryPath,3.1.0
faker.system.filePath,3.1.0
faker.system.semver,3.1.0
faker.system.networkInterface,7.4.0
faker.vehicle,5.0.0
faker.vehicle.faker,6.0.0
faker.vehicle.vehicle,5.0.0
faker.vehicle.manufacturer,5.0.0
faker.vehicle.model,5.0.0
faker.vehicle.type,5.0.0
faker.vehicle.fuel,5.0.0
faker.vehicle.vin,5.0.0
faker.vehicle.color,5.0.0
faker.vehicle.vrm,5.4.0
faker.vehicle.bicycle,5.5.0
faker.word,6.0.0
faker.word.faker,6.0.0
faker.word.adjective,6.0.0
faker.word.adverb,6.0.0
faker.word.conjunction,6.0.0
faker.word.interjection,6.0.0
faker.word.noun,6.0.0
faker.word.preposition,6.0.0
faker.word.verb,6.0.0
faker.locales,2.0.1
faker.locales.af_ZA,6.0.0
faker.locales.ar,5.0.0
faker.locales.az,4.0.0
faker.locales.cz,4.0.0
faker.locales.de,2.0.1
faker.locales.de_AT,2.0.1
faker.locales.de_CH,2.0.1
faker.locales.el,6.0.0
faker.locales.en,2.0.1
faker.locales.en_AU,2.0.1
faker.locales.en_AU_ocker,5.0.0
faker.locales.en_BORK,2.0.1
faker.locales.en_CA,2.0.1
faker.locales.en_GB,2.0.1
faker.locales.en_GH,6.0.0
faker.locales.en_IE,3.0.0
faker.locales.en_IND,2.0.1
faker.locales.en_NG,6.0.0
faker.locales.en_US,2.0.1
faker.locales.en_ZA,5.0.0
faker.locales.es,2.0.1
faker.locales.es_MX,3.0.1
faker.locales.fa,2.0.1
faker.locales.fi,5.1.0
faker.locales.fr,2.0.1
faker.locales.fr_BE,6.0.0
faker.locales.fr_CA,3.0.0
faker.locales.fr_CH,5.0.0
faker.locales.ge,2.1.5
faker.locales.he,5.5.3
faker.locales.hr,5.3.0
faker.locales.hu,6.3.0
faker.locales.hy,5.4.0
faker.locales.id_ID,3.1.0
faker.locales.it,2.0.1
faker.locales.ja,2.0.1
faker.locales.ko,2.0.1
faker.locales.lv,6.0.0
faker.locales.mk,6.0.0
faker.locales.nb_NO,2.0.1
faker.locales.ne,5.4.0
faker.locales.nl,2.0.1
faker.locales.nl_BE,5.0.0
faker.locales.pl,2.0.1
faker.locales.pt_BR,2.0.1
faker.locales.pt_PT,5.0.0
faker.locales.ro,5.0.0
faker.locales.ru,2.0.1
faker.locales.sk,2.0.1
faker.locales.sv,2.0.1
faker.locales.tr,2.1.5
faker.locales.uk,3.0.0
faker.locales.ur,6.0.0
faker.locales.vi,2.0.1
faker.locales.zh_CN,2.0.1
faker.locales.zh_TW,2.1.5
faker.locales.zu_ZA,6.0.0

[ST-DDT]

Can you publish that script here in case we have to run it again in the future?

[matthewmayer]

Sure thing, it's a bit hacky but I'll upload it to a gist and post the link here. I guess it would be reasonably easy to modify it to modify the source files to add the correct @since annotations. That would be a one off job and then after that @since would just need to be added to newly added methods.

[matthewmayer]

here you go

https://github.com/matthewmayer/fakersince

[matthewmayer]

I went ahead and modified my script to actually add the @since tags and expose them in the API docs.

This is PR: #1337

[matthewmayer]

Thanks for the help getting my PR ready to merge :) The "Available since" messages are already live on the docs site e.g. https://fakerjs.dev/api/name.html