@see tag contents not parsed as expected

[webOS101]

The @see tag (http://usejsdoc.org/tags-see.html) is supposed to support @links as well as free-form text. Unfortunately, documentation does not produce proper link-type output.

Example:

@see {@link http://github.com|GitHub}

[tmcw]

Thanks for the report!

As far as I can see, we're correctly parsing link syntax in @see tags, but don't yet output it in HTML or Markdown modes. I'll look into output today.

[webOS101]

Thanks, Tom. I'm curious if there's someplace where discussion about the direction of documentation takes place? Having documented a reasonably sized framework I find myself fighting against documentation on a fairly regular basis. I went in to fix some of the problems I was having and I found test cases that enforce what I consider to be bad behavior. Given someone explicitly added these cases, I abandoned my work. I also see that a number of tickets that touch on these areas are not being picked up.

[tmcw]

Hey Roy,

This is the main place where discussion around documentation happens. I try to reply to as many issues as possible, balancing with my more work-related tasks - unfortunately I have to prioritize work as a result and some issues I don't reply to within weeks or even months. Additional contribution energy would be hugely appreciated, and I'm happy to review whether tests for potentially bad behavior are intentional or the result of mistakes or incorrectly regenerated test fixtures.

• Tom

[tmcw]

And since there isn't a single place for the current direction of the project:

• Ideally I'd be working on a refactor of the theme system, something that I've wanted to implement for quite a while. Main goals being robust permalink support, potentially switching to React so that we don't have to grapple with errors in lodash and with HTML nonsense.
• Secondarily, checking all the boxes of tag support ( Tag Support Master Ticket #9 ), so that we have 100% JSDoc coverage
• But, given the deep complexity of tags like @param and member inference, I'm spending a lot of my time fixing bugs and covering corner cases.

Given more contributors or more time, this list could be more exciting, but alas it's a big project and the first priority for me is robustness, so that's where I'm spending time.

[webOS101]

Tom, thanks for the information. I think what might be very useful is a 'philosophy' doc that explains a bit about what is expected from the documentation process and how it might apply to some common scenarios. In part, I feel like maybe I chose the wrong path and am having to fight against the tool rather than figure out how to work with it. I understand that a general-purpose tool like documentation by necessity will not be a perfect fit for everyone. Maybe a 'cookbook' would be helpful?

[webOS101]

Oh, I should mention that we're using the json output, not markdown or html. So, the @link tags aren't outputting in @see in all output formats.

[tmcw]

Are you sure? I just tested with the master and beta.18, and the tag is correctly parsed & output in JSON in both:

[
  {
    "description": "",
    "tags": [
      {
        "title": "see",
        "description": "{@link http://github.com/|github}",
        "lineNumber": 1
      }
    ],
    "loc": {
      "start": {
        "line": 1,
        "column": 0
      },
      "end": {
        "line": 3,
        "column": 3
      }
    },
    "context": {
      "loc": {
        "start": {
          "line": 4,
          "column": 0
        },
        "end": {
          "line": 4,
          "column": 17
        }
      },
      "file": "/Users/tmcw/src/documentation/test.js"
    },
    "sees": [
      {
        "type": "root",
        "children": [
          {
            "type": "paragraph",
            "children": [
              {
                "type": "link",
                "url": "http://github.com/",
                "title": null,
                "jsdoc": true,
                "children": [
                  {
                    "type": "text",
                    "value": "github"
                  }
                ],
                "position": {
                  "start": {
                    "line": 1,
                    "column": 1,
                    "offset": 0
                  },
                  "end": {
                    "line": 1,
                    "column": 34,
                    "offset": 33
                  },
                  "indent": []
                }
              }
            ],
            "position": {
              "start": {
                "line": 1,
                "column": 1,
                "offset": 0
              },
              "end": {
                "line": 1,
                "column": 34,
                "offset": 33
              },
              "indent": []
            }
          }
        ],
        "position": {
          "start": {
            "line": 1,
            "column": 1,
            "offset": 0
          },
          "end": {
            "line": 1,
            "column": 34,
            "offset": 33
          }
        }
      }
    ],
    "name": "add",
    "kind": "function",
    "members": {
      "instance": [],
      "static": [],
      "events": []
    },
    "path": [
      {
        "name": "add",
        "kind": "function"
      }
    ],
    "namespace": "add"
  }
]

[webOS101]

Ah, yes, it does do -that-. But what I expected was more along the lines of what happens in a description field, with child nodes and such-not.

[webOS101]

Oh... I see, the sees section now. I will go double-check my output. The @see tag was where I expected to find it.

[webOS101]

Alrighty then, this was just a case of user error. I found the output. And I wrote such a nice regex to parse that @see tag. :(