Implement @external tag for External Types

[YetAnotherClown]

Resolves #8

This implements a simple @external <name> <url> tag for linking to External Types.

In this implementation, @external is a tag which can be defined in any doc comment, and then used in any doc comment.

The url argument simply links to any external documentation page, e.g. https://eryn.io/roblox-lua-promise/api/Promise.

Notable Changes

• The passing test all_tags was updated to include the usage of the external type. A new passing test external_types was added to test the new external tag.
• Name conflicts with the @class and @external tag are now reported as an error.
• Added tests for name conflicts.

Example

--- @class MyClass
--- A sample class.
local MyClass = {}
MyClass.__index = MyClass

--[=[
	This is a function that will return a [Promise].

	@method returnAPromise
	@within MyClass
	@external Promise https://eryn.io/roblox-lua-promise/api/Promise
	@return Promise -- The Promise it returns
]=]
function MyClass:returnAPromise()
	-- Returns a roblox-lua-promise
end

--- @prop promise Promise
--- @within MyClass
--- I can also use the Promise type here!

[evaera]

I'm not sure this matches the original vision for the @external tag. I don't think it should need to be associated with a class. Rather, it's just a name that is ultimately hyperlinked on the docs website, similar to how all of the Roblox classes are hyperlinked. Just a mapping of names to links.

[YetAnotherClown]

@evaera If you could find some time to share more on the original vision for the @external tag I would be happy to revise my implementation. I tried looking for any previous discussion on it prior, but I wasn't able to find anything. Thank you.

[evaera]

Just what's specified in the issue, it's pretty simple. No need for @class or anything else. The external names should just turn into a list of additional names, like the Roblox classes are today, which are hyperlinked when they appear in the typical type positions where we do hyperlinks now.

[YetAnotherClown]

The dependency on the @class tag has been removed, the @external tag can now be used on any doc comment. The PR Description and the Documentation in the PR has been updated to reflect this.

[evaera]

Excellent work, thank you. I noticed that we have a "don't do this" warning for defining multiple external types with the same name. Would it be possible to simply make this error instead? I believe we already error if you define multiple classes of the same name.

Also, does it work when you define an external type by itself in a doc comment? Like:

--[=[
@external test example.com
]=]

..with no other class, function, type, etc. associated. I didn't see an example like this in the tests.

[YetAnotherClown]

Just tested it, external types by themselves in a doc comment like your example will fail, expecting an explicit kind tag. Do you expect this to work? Currently external types are stored on doc entries as a vector called external_types, I would have to find another way to output the external types from the Extractor.

I also just tested having multiple classes of the same name, it doesn't error for me. I can implement something though to support warning for both classes and external tags if they have the same name.

[evaera]

I think that erroring if there are name conflicts makes the most sense, since it’s invalid and is likely a mistake. We have other errors for things that are invalid (I guess not for multiple classes of the same name though, but we probably should have had that to begin with).

And yeah, I think it would be useful for those to work without having to be attached to a doc entry of another kind. I think we have an issue open for being able to put multiple doc comments in one comment. So that would be separate work, but would allow you to put multiple external tags in one block. For now, I think having external tags be their own kind of doc comment is best

[YetAnotherClown]

Added functionality for erroring on name conflicts with any tag we specify, I just set it to @class and @external. Added tests for it, fixed the other tests that broke because of this.

[evaera]

Looks good!