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

bugfix @see tag does not work with static function/member #178

Closed
wants to merge 1 commit into from

Conversation

xsjad0
Copy link

@xsjad0 xsjad0 commented May 12, 2021

Using JSDocs @see tag to reference a static function/member causes Sphinx to crash with the following error message

image

Since we've added the directive js:staticfunction we also have to specify a new object type within the JS Domain that allows Sphinx to resolve the any reference.

This example code works now:

    /**
     * SomeMembers
     */
    class SomeMembers {
        /**
        * Some static member.
        *
        * @returns {void}
        */
        static someStaticMember() {
            // No use of this
        }

        /**
        * Non-static member
        *
        * @see someStaticMember
        * @returns {void}
        */
        nonStaticMember() {
            this.nonStatic = true;
        }
    }

It's also possible to reference a static function/member by using the js:func: role

    :js:func:`SomeMembers.someStaticMember`

Unfortunately, there is no way extend Sphinx to define the correct index text for static functions.

See sphinx.domains.javascript.py code snippet

def get_index_text(self, objectname: str, name_obj: Tuple[str, str]) -> str:
    name, obj = name_obj
    if self.objtype == 'function':
        if not obj:
            return _('%s() (built-in function)') % name
        return _('%s() (%s method)') % (name, obj)
    elif self.objtype == 'class':
        return _('%s() (class)') % name
    elif self.objtype == 'data':
        return _('%s (global variable or constant)') % name
    elif self.objtype == 'attribute':
        return _('%s (%s attribute)') % (name, obj)
    return ''

Unless we generate a JS index, we may not notice any restriction...
What do you think??

@willkg willkg added this to the 3.2 milestone Feb 23, 2022
@willkg willkg modified the milestones: 3.2.0, 3.next Dec 13, 2022
willkg added a commit that referenced this pull request Dec 16, 2022
This fixes the objtype xref when the thing is a staticfunction that was
added to sphinx-js in pr #174.

Now `@see` should work and the index should show the right text.

Based on work from xsjad0.
@willkg
Copy link
Member

willkg commented Dec 16, 2022

I redid the suggested fix in #217 after going through and making sure there weren't any changes in Sphinx that would cause us to do something else. Thank you for the work sleuthing it out!

@willkg willkg closed this Dec 16, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants