How to document that a name of a variable can be different in another taxonomy?

33 Views Asked by At

For example, the taxonomies for community chat in Discord and Messenger are different, but they serve the same functionality:

Discord Messenger
Server Community
Text Channel/Forum Channel Community Chat
Channel Thread/Forum Post Sidechat

In my code I want to use the taxonomy of Discord to have better readability experience. Is there a tag to document that the variable names can be different in another taxonomy?

/**
 * @tagForFunctionName doStuff - This can work on both Discord servers or Messenger community
 * @tagForVariableName server, servers - In Discord it's called server. In Messenger it's call community
 * @tagForVariableName channel, channels - In Discord it's called channel. In Messenger it's call community chat
 * @tagForVariableName thread, threads - In Discord it's called thread or topic. In Messenger it's call sidechat
 */
function doStuff(){
    const server = ...
    const servers = ...
    const channel = ...
    const channels = ...
    const thread = ...
    const threads = ...
} 
2

There are 2 best solutions below

2
tumelo dlodlo On

Use the tag @context tag from json linked data . Then in the linked document (inside the comments or separate document) define the alternative identifier names using Json linked data.

/**
 * This function does 1, 2, 3, 4
 * 
 * @see 'JSON-LD the context' https://www.w3.org/TR/json-ld/#the-context
 * @context: {
 *    doStuff: "https://path-to-doStuff-documentation-at-Messenger",
 *    server: "https://path-to-community-docs-at-Messenger",
 *    channel: "https://path-to-community-chat-docs-at-Messenger",
 *    thread: "https://path-to-topic-documentation-at-Messenger"
 * }
 */
function doStuff() {
    const server = ...
    const channel = ...
    const thread = ...
} 
2
tumelo dlodlo On

Alternative: "The @see tag allows you to refer to another symbol or resource that may be related to the one being documented." - jsdoc

    function doStuff() {
        /**
         * @see 'In Messenger its call community' https://path-to-community-docs-at-Messenger
         */
        const server = ...

        /**
         * @see 'In Messenger its call community chat' https://path-to-community-chat-docs-at-Messenger
         */
        const channel = ...

        /**
         * @see 'In Messenger its call sidechat' https://path-to-topic-documentation-at-Messenger
         */
        const thread = ...
    }