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

[ELLIOTTCABLE]

The JSdoc documentation for ‘namepaths’ 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 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. (=

[ELLIOTTCABLE]

(Also, of note, I'm happy to dive into the codebase and see what I can do about a pull-request to support this, if it's of interest — I'm posting more to gauge acceptance than as a feature-request.)

[tmcw]

I am totally with you on the namepaths stuff: namepaths seem like yet-another-way to address JavaScript and they have plenty of gotchas, like escaping, an inability to address indexed properties, and so on.

I'm very interested in this proposal, though I'm not sure that the :: proposal in JS matches the intent in this ticket - like MyConstructor::instancemember would be equivalent to instancemember(MyConstructor), not to (new MyConstructor()).instancemember().

---

So, yep, totally agree on the intent, not 100% sure that the meaning of :: is close enough to what we're trying to indicate. Oh, and re: @link syntax etc: I'm scheming a documentation.js successor that will likely drop that and other JSDoc tags - dropping types in JSDoc, and likely following 'just Markdown' syntax or something more markdown-like.

[ELLIOTTCABLE]

Well, I'm not too attached to which character, as long as it's not a g/d comment-character! 🤣

What about abandoning them entirely and going entirely JavaScript? Just enforcing MyConstructor.prototype.instancemember?

Alternatively, we could make up a new syntax, although that defeats the point … MyConstructor..instancemember, implying we simply elided the word prototype?

---

Thank god for ‘just markdown’; that was going to be my next feature-request (and unfortunately just a request, because unlike a simple parser-hack, I don't feel capable of re-implementing whatever powers the linkage): “can we replace tags with heuristics over Markdown features?”

The vast majority of my documentation looks like:

# The links from one `Thing` to another are encoded as `Relation` objects, which are further
# annotated with the property of **‘ownership’**: an object that ‘owns’ an object below it in the
# graph is claiming that object as a component of the *overall data-structure* that the parent
# object represents. (Put simply: a series of ownership-annotated links in the datagraph describe a
# single data-structure as a subgraph thereof.)
#
# These `Relation`s are stored in an ordered `Array`; manipulable via `::set`, `::push`,
# `::pop`, `::shift`, and `::unshift`. When structured as a dictionary (a list of key-value
# ‘pairs’), the values are searchable by `::find`; and the apparent key / value of a pair are
# exposed by `::keyish` and `::valueish`.

I'd much-prefer to not replace the simple-and-readable (in the code, as opposed to in the produced HTML documentation) markdown `backticks` — even if that means it's non-predicable w.r.t. what will be linked, and/or whether linking will fail. (I'd rather missing/broken links in the HTML documentation, than fugly and unreadable documentation encoded permanently into my damn source-code!)

[tmcw]

What about abandoning them entirely and going entirely JavaScript? Just enforcing MyConstructor.prototype.instancemember?

I'm down for this. Simple, exact, with a slight lengthiness penalty that I think is worth the trade.

[anthony-redFox]

@ELLIOTTCABLE if you skip the prototype word you get confusing static and instance method (a the difference one point):

MyConstructor..instanceMember
MyConstructor.staticMethod

The prototype object in the past because when you write a code in ES6 syntactic you don't thinking about prototype. (It just like C# or Java Classes)

The jsDoc syntactic of link like MyConstructor#instanceMemberis conflict with private variables in new Specification. https://github.com/tc39/proposal-class-fields

In my head two options

1. If you want to link on instance of something you should write a clear JS code like {@link (new MyConstructor).instancemember }

• It clear because it is simple valid JS code

2. Another option we can add @instanceName myClass for class and for link you can use {@link myClass.instancemember }
   Classes should be start with a capital letter and an instance of class small one (CamelCase notation)
   Node.js uses the same option in own documentation - http://nodejs.org/dist/latest-v6.x/docs/api/buffer.html

@tmcw any thoughts?

[tmcw]

I'd rather not rely on class naming conventions for this kind of namespace thing - though you should name classes with an upper, not everyone does, and often people also name instances with an upper, due to habits from other languages. It seems like it'd be a bit too magic.

Re:

The prototype object in the past because when you write a code in ES6 syntactic you don't thinking about prototype. (It just like C# or Java Classes)

I'm not sure that this is a disqualifier: though ES6 syntax lets you avoid mentioning the prototype, they are still prototype-based under the hood:

class B { method() {return 'hi'} }
B.prototype.method() // -> 'hi'

I think even for ES6 classes, .prototype. is the way you'd reference prototype methods. It'd be relatively simple to parse, unambiguous, and so on.

[ELLIOTTCABLE]

I'm still stuck on .prototype., as well. (Also, remember, since you're presumably retaining backwards-compatibility with JSdoc, this isn't replacing #, it's just a more-JavaScript-y alternative; so there's still a short syntax, even if it's not very JavaScript-y.)

Edit: Although, to be clear, I still love :: — been using it for years upon years in CoffeeScript et al.

[anthony-redFox]

It is true, ES6 based on prototype and you have access on My Class.prototype.method
But I mean, may be, for new JS Developers who develop on ES6+ can be not clear or not obvious writing in documentation a prototype word.

So .prototype. also fine for me.

[jfirebaugh]

.prototype. seems to be what MDN has settled on as well: