search

jelly-beam / rebar3_ex_doc

rebar3 plugin for generating docs with ex_doc
Apache License 2.0
43 stars 13 forks source link

Type links are invalid #38

Closed eproxus closed 1 year ago

eproxus commented 1 year ago

When using the {@type mytype()} syntax, a link is generated to #type-mytype but the ExDoc equivalent should be #t:mytype/0 it seems.

paulo-ferraz-oliveira commented 1 year ago

@eproxus, I'm not sure this is dealt with by the plugin. I also have a similar issue when using {@link ...}. I'm not sure this is an ex_doc issue, tbh. Maybe @starbelly knows best if this is from the chunk generation, or something else (?)

paulo-ferraz-oliveira commented 1 year ago

@starbelly, tested this again, and, as-is, this throws an exception with ex_doc but generates a proper link with EDoc.

starbelly commented 1 year ago

I will take a gander.

paulo-ferraz-oliveira commented 1 year ago

Yeah, I'm also setting this up to see if it's easily fixable next to ex_doc.

starbelly commented 1 year ago

@paulo-ferraz-oliveira An example would be good, it works for me, but @eproxus is referencing a form with curly brackets, which I'm not familar with. Also, edoc complains saying @type is deprecated btw.

paulo-ferraz-oliveira commented 1 year ago

Yeah, I can't get all of EDoc to work as per its documentation either.

The form @eproxus is mentioning is indeed deprecated, but still supported by EDoc...

starbelly commented 1 year ago

Technically speaking @type period is deprecated AFAIK. The {@type {option, thing()@}} I could only find used in edoc itself and two places in epp_dodger. Its use seems limited to when you have a property list for options, but maybe there's other uses for it? A tad off subject from the fact that it can cause a crash, but still interesting and all simply a "FWIW".

paulo-ferraz-oliveira commented 1 year ago

Yeah, I'll let you decide on this one. If the ex_doc fix lands maybe we can close this, unless @eproxus is interested in writing some tests cases for which we'd need to see the code pass 😉

paulo-ferraz-oliveira commented 1 year ago

The pull request mentioned above was merged. No further changes regarding {@type ...} are expected. I don't think that this addresses your issue, but ex_doc's maintainers preferred a simpler solution (simply not crash).

I referred "Links are not usable, because generated HTML..." and ultimate we got "I'd strip out the \ and just leave \ but it definitely doesn't hurt to keep it this way for now."

paulo-ferraz-oliveira commented 1 year ago

The mentioned pull request is already merged, tagged, released (ex_doc) and imported and released here (rebar3_ex_doc). Closing...

eproxus commented 1 year ago

Didn't exactly understand what was said here. What would the alternative to {@type ...} be to achieve type links using EDoc + the ex_doc plugin?

paulo-ferraz-oliveira commented 1 year ago

@eproxus, there is no alternative, as of this moment.

ex_doc (via the pull request) didn't accept that valid links were generated: https://github.com/elixir-lang/ex_doc/pull/1787#issuecomment-1744295489 (here's the test I wrote to make sure generation created at least "a" link, and that's what was accepted).

So I don't think that, at least now, the plugin can move much more forward on this.