Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Mark and visualize aliases for the api-docs #1183

Closed
ST-DDT opened this issue Jul 23, 2022 · 1 comment
Closed

Mark and visualize aliases for the api-docs #1183

ST-DDT opened this issue Jul 23, 2022 · 1 comment
Assignees
Labels
c: docs Improvements or additions to documentation c: feature Request for new feature p: 1-normal Nothing urgent s: waiting for user interest Waiting for more users interested in this feature
Milestone

Comments

@ST-DDT
Copy link
Member

ST-DDT commented Jul 23, 2022

Clear and concise description of the problem

Methods should refer to related methods to improve visibility for developers, so they can find replacement/alternative methods more easily.

E.g. The developers searches for an android app package name. The developer finds the hacker module with the appleBundleId, then sees that it is an alias and now finds the internet.domainName method that they use until they PR their new method here.

There might also be value in the reverse alias.
E.g. the developer wants and appleBundleId, but searches for reverse domain names and thus stumples across the internet.domainName method and there they discover that the method they need exist already.

Suggested solution

Use jsdocs @alias to refer to the core of an implementation.

E.g.

[...]
 * @alias faker.internet.domainName
 */
appleBundleId() {

However there are some things that needs to be defined, before we can add this.

  1. Where do we add these:
  • All methods that depend on another faker method (e.g. faker.datatype.number() and faker.datatype.boolean())
  • All methods that depend mostly depend on a single other faker method (faker.random.arrayElement())
  • Only methods that are an alias for a non helper/random/datatype method (e.g. faker.internet.domainName(params)
  1. Which information should we include in the link
  • Only the method name faker.internet.domainName
  • Method with parameters faker.internet.domainName(reverse: true)
  1. Should we include links back to the aliases
    e.g. faker.internet.domainName <-> faker.hacker.appleBundleId
  • Yes (automatically)
  • Sometimes (manually)
  • No
  1. How should they be displayed?
  • Similar to @see? (Above or below or mixed with @see?)
  • ???

Alternative

  • Use @see to link these methods together
  • Use js/ts AST to generate the alias references automatically
  • Don't link the methods together

Additional context

The issue originally came up during #1154 .

@ST-DDT ST-DDT added c: docs Improvements or additions to documentation c: feature Request for new feature p: 1-normal Nothing urgent s: needs decision Needs team/maintainer decision labels Jul 23, 2022
@ST-DDT ST-DDT added this to the v7 - Current Major milestone Jul 23, 2022
@ST-DDT ST-DDT self-assigned this Jul 23, 2022
@ST-DDT ST-DDT moved this to Awaiting Review in Faker Roadmap Jul 23, 2022
@ST-DDT ST-DDT added s: on hold Blocked by something or frozen to avoid conflicts and removed s: needs decision Needs team/maintainer decision labels Sep 7, 2022
@ST-DDT ST-DDT removed the s: on hold Blocked by something or frozen to avoid conflicts label Oct 12, 2022
@ST-DDT ST-DDT moved this from Awaiting Review to Todo in Faker Roadmap Jan 26, 2023
@ST-DDT ST-DDT added the s: waiting for user interest Waiting for more users interested in this feature label Jan 26, 2023
@ST-DDT
Copy link
Member Author

ST-DDT commented Oct 5, 2023

This is mostly covered by @see tags already.

@ST-DDT ST-DDT closed this as completed Oct 5, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c: docs Improvements or additions to documentation c: feature Request for new feature p: 1-normal Nothing urgent s: waiting for user interest Waiting for more users interested in this feature
Projects
No open projects
Status: Todo
Development

No branches or pull requests

1 participant