[WIP] Added html and markdown url to documentation_link

[vzamanillo]

The html and markdown url should be useful to visit the documentation in a browser or to parse the markdown and extract information about the rule (with some linters, etc...).

[vzamanillo]

Thoughts about how to solve the ABC size metric warning? I was thinking in split the method, but should not work because there will be too many methods.

[mvz]

Hi @vzamanillo, thanks for your contribution. I have a question and some remarks:

• Do you have a concrete example of what you would like a linter to do with the markdown URL?
• The 'raw' URL you used seems to be a github-internal URL that may change. The html page contains a link to the raw content that linters could follow. Alternatively, just changing 'blob' to 'raw' in the given URL gives the URL for that link.
• Your proposed change is a breaking change. Let's see if we can accommodate your use case with a non-breaking change.

[mvz]

(Don't worry about the ABC size metric for now.)

[vzamanillo]

Hi Matijs,

Do you have a concrete example of what you would like a linter to do with
the `markdown` URL?

I have not my branch for linter-reek published yet but the intention is the same as linter-rubocop does, to show the rule description on linter marker tooltip, you can check the getMarkDown source code.

The 'raw' URL you used seems to be a github-internal URL that may change. The html page
contains a link to the raw content that linters could follow. Alternatively,
just changing 'blob' to 'raw' in the given URL gives the URL for that link.

This is what my actual implementation does, replace the URL parts to get the raw content URL.

Your proposed change is a breaking change. Let's see if we can accommodate your use
case with a non-breaking change.

Thanks, let me know about anything I can do.

[mvz]

This is what my actual implementation does, replace the URL parts to get the raw content URL.

I'm not following. In this PR you replace almost the entire URL? My point is that your linter can take the URL that Reek already provides and replace blob by raw to get the data you want. Maybe I'm misunderstanding what you are trying to say here?

The screen shot for linter-rubocop you posted shows one problem with your approach: The documentation linked to was never created for non-human consumption, so you may get all kinds of artifacts in the output. There is no guarantee Reek's documentation will keep the structure it has currently.

[vzamanillo]

This is what my actual implementation does, replace the URL parts to get the raw content URL.

I'm not following. In this PR you replace almost the entire URL? My point is that your linter can take the URL that Reek already provides and replace blob by raw to get the data you want. Maybe I'm misunderstanding what you are trying to say here?

Sorry, I was talking about my pending linter-reek implementation who's consume the raw markdown data, not about this PR.

The screen shot for linter-rubocop you posted shows one problem with your approach: The documentation linked to was never created for non-human consumption, so you may get all kinds of artifacts in the output. There is no guarantee Reek's documentation will keep the structure it has currently.

My purpose was to use a pattern in the documentation to get a brief description of the reek warning, for example, all reek documentation written in markdown has an "Introduction" section that could be used, it could be interesting.

[mvz]

Sorry, I was talking about my pending linter-reek implementation who's consume the raw markdown data, not about this PR.

Ok, that explains it. I think that's actually a good approach for what you're trying to do.

all reek documentation written in markdown has an "Introduction" section that could be used

I'm afraid there's no guarantee it will stay that way.

My advice would be to put a link in the tooltip (if that's possible), that will open the page in the browser when clicked. It's beneficial for users of Reek to read the full docs for each smell.

[vzamanillo]

Sorry, I was talking about my pending linter-reek implementation who's consume the raw markdown data, not about this PR.

Ok, that explains it. I think that's actually a good approach for what you're trying to do.

all reek documentation written in markdown has an "Introduction" section that could be used

I'm afraid there's no guarantee it will stay that way.

I get it.

My advice would be to put a link in the tooltip (if that's possible), that will open the page in the browser when clicked. It's beneficial for users of Reek to read the full docs for each smell.

This is what my linter-reek implementation is doing actually.

Thanks!

[vzamanillo]

You can check this linter-reek PR in case you are curious to see the implementation that I mentioned earlier.