documentationjs / documentationjs/documentation

Use JavaScript-native (ES.next / CoffeeScript) `::` as an alternative to `#` for instance-method paths

Open
#857 9 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

The [JSdoc documentation for ‘namepaths’](http://usejsdoc.org/about-namepaths.html) declares the following syntax for instance methods:

MyConstructor#instanceMember

This is meaningless, in JavaScript … and perhaps this is a bit subjective, but having grown up in Ruby et al years ago, it's **ugly**. More importantly, it's just Yet Another Thing to Learn for newcomers learning JSdoc'd codebases in JavaScript; and besides the equally-horrendous-but-probably-unfixable `{@link syntax}`, it's the only one that doesn't map directly to the equivalent source-code syntax.

Meanwhile, there's an old and well-accepted syntax shortcut for `.prototype.`: CoffeeScript's `::`! ([Hopefully coming soon](https://github.com/tc39/proposal-bind-operator) to ECMAscript, although admittedly only as a stage-0 right now.)

Perhaps this is merely aesthetic and has no place here, but after the billionth time typing `Foo#bar` in documentation tags to point to a method that's written, tested, and documented-in-prose as `Foo::bar`, I thought I'd at least drop an Issue out there. `(=`

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.