@see tag is missing

[thiemowmde]

The meaning of @see is very close to {@link} so it should be (excuse my oversimplification) pretty easy to implement.

Or make @see an alias for @inheritdoc. Is there a way I can do this by my own? I think this could also be very nice. Except there are multiple @see, then it's hard to decide which one should be used.

Would be very cool to have this since this is one of the few tags we are using a lot in our code. Thanks!

[nene]

I think I should consider building support for @see in JSDuck.

You can implement @see as a custom tag: https://github.com/senchalabs/jsduck/wiki/Custom-tags

[thiemowmde]

We tried to make it an alias of @inheritdoc and were partially successful. Our tiny .rb file works. Very nice interface. But unfortunately JSDuck can't find the target methods because we have them organized in namespaces JSDuck isn't aware of (e.g. jQuery widgets). Any suggestion how to fix this?

[nene]

Well, in my understanding the @see tag normally (e.g. in JSDoc) works like an alias of the {@link}:

@see SomeClass
is considered about the same as
See {@link SomeClass}

@inheritdoc is quite a different beast - it pulls in documentation from other class. Not really sure how you managed to implement @see with it...

But if you want to link to external resources, you should just use Markdown links with full URL-s.

[thiemowmde]

I know. :-) I'm totally fine with the See {@link SomeClass} approach.

[Krinkle]

In various Wikimedia repositories we implement the @see tag as follows:

class SeeTag < CommonTag
  def initialize
    @tagname = :see
    @pattern = "see"
    super
  end

  def format(context, formatter)
    position = context[:files][0]
    context[@tagname].each do |tag|
      tag[:doc] = '<li>' + render_long_see(tag[:doc], formatter, position) + '</li>'
    end
  end

  def to_html(context)
    <<-EOHTML
      <h3 class="pa">Related</h3>
      <ul>
      #{ context[@tagname].map {|tag| tag[:doc] }.join("\n") }
      </ul>
    EOHTML
  end

  def render_long_see(tag, formatter, position)
    if tag =~ /\A([^\s]+)( .*)?\Z/m
      name = $1
      doc = $2 ? ': ' + $2 : ''
      return formatter.format("{@link #{name}} #{doc}")
    else
      JsDuck::Logger.warn(nil, 'Unexpected @see argument: "'+tag+'"', position)
      return tag
    end
  end
end

Practically very similar to @fires, except that it expands to a plain link to another member rather than member of type event.

Usage:

/**
 * Get the offset of the node.
 *
 * @see ve.dm.Node#getOffset
 * @returns {number} Offset
 */
ve.ce.Node.prototype.getOffset = function () {
    return this.model.getOffset();
};

Rendering: