New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[docs] expand linter - attributes - defaults #1240

Open
nvtkaszpir opened this Issue Mar 18, 2018 · 9 comments

Comments

4 participants
@nvtkaszpir
Contributor

nvtkaszpir commented Mar 18, 2018

http://sublimelinter.readthedocs.io/en/stable/linter_attributes.html#defaults

Right now the description of the defaults is without examples - you have to dig through multiple repos of other plugins to get the idea how it works.

Maybe there should be some examples explaining in detail what happens there?

@nvtkaszpir nvtkaszpir changed the title from Feature: docs, expand linter - atriibutes - defaults to Feature: docs, expand linter - attributes - defaults Mar 18, 2018

@braver

This comment has been minimized.

Show comment
Hide comment
@braver

braver Mar 19, 2018

Member

If you’re creating a new linter plugin, the docs tell you what you can use. If you need more details I expect you to read the implementation and its comments, or look for examples in our most popular plugins.

Some very basic examples would of course help, but the old docs basically repeated the entirety of several plugins. Except of course the docs weren’t maintained and very much out of sync with the reality of those plugins. So, if you keep that in mind I’d welcome some additions to the docs here.

Member

braver commented Mar 19, 2018

If you’re creating a new linter plugin, the docs tell you what you can use. If you need more details I expect you to read the implementation and its comments, or look for examples in our most popular plugins.

Some very basic examples would of course help, but the old docs basically repeated the entirety of several plugins. Except of course the docs weren’t maintained and very much out of sync with the reality of those plugins. So, if you keep that in mind I’d welcome some additions to the docs here.

@kaste

This comment has been minimized.

Show comment
Hide comment
@kaste

kaste Mar 19, 2018

Contributor

You just need to git blame here. We had relatively good documentation for the defaults section and the current documentation is not even correct.

Also: executable is deprecated

Contributor

kaste commented Mar 19, 2018

You just need to git blame here. We had relatively good documentation for the defaults section and the current documentation is not even correct.

Also: executable is deprecated

@braver

This comment has been minimized.

Show comment
Hide comment
@braver

braver Mar 19, 2018

Member

executable is deprecated

Why not remove it then?

Member

braver commented Mar 19, 2018

executable is deprecated

Why not remove it then?

@kaste

This comment has been minimized.

Show comment
Hide comment
@kaste

kaste Mar 19, 2018

Contributor

I just read this thing, lol

Contributor

kaste commented Mar 19, 2018

I just read this thing, lol

@braver

This comment has been minimized.

Show comment
Hide comment
@braver

braver Mar 20, 2018

Member

I'd much rather do this case by case, because not a lot of plugins get made a given week and we might be documenting stuff that's already clear or discoverable. Lots of plugins can be just 5 lines of configuration. And we do have a bunch of examples out there.

Having nice docs is cool though, so definitely appreciated if anyone wants to contribute here.

Member

braver commented Mar 20, 2018

I'd much rather do this case by case, because not a lot of plugins get made a given week and we might be documenting stuff that's already clear or discoverable. Lots of plugins can be just 5 lines of configuration. And we do have a bunch of examples out there.

Having nice docs is cool though, so definitely appreciated if anyone wants to contribute here.

@FichteFoll

This comment has been minimized.

Show comment
Hide comment
@FichteFoll

FichteFoll Mar 20, 2018

Contributor

Methods are also severely lacking. I used context_sensitive_executable_path earlier today, but that's not mentioned in the docs and I probably wouldn't know about it if I hadn't followed development for months.

Contributor

FichteFoll commented Mar 20, 2018

Methods are also severely lacking. I used context_sensitive_executable_path earlier today, but that's not mentioned in the docs and I probably wouldn't know about it if I hadn't followed development for months.

@nvtkaszpir

This comment has been minimized.

Show comment
Hide comment
@nvtkaszpir

nvtkaszpir Mar 22, 2018

Contributor

AFAIR SublimeLinter does not have any decent docstrings exported to sphinx.

Contributor

nvtkaszpir commented Mar 22, 2018

AFAIR SublimeLinter does not have any decent docstrings exported to sphinx.

@braver braver changed the title from Feature: docs, expand linter - attributes - defaults to [docs] expand linter - attributes - defaults May 17, 2018

@braver

This comment has been minimized.

Show comment
Hide comment
@braver

braver May 17, 2018

Member

AFAIR SublimeLinter does not have any decent docstrings exported to sphinx.

Nope, we seriously reduced the number of docstrings going into 4.0. Most of them we're outdated and incorrect even before we started working on SL4.

Perhaps waiting for demand for docs is a chicken and egg kind of problem, but as I understand our current maintainers' priorities, documentation is not going to happen all by itself either. Anyone who wants to add some notes, that's super welcome!

Member

braver commented May 17, 2018

AFAIR SublimeLinter does not have any decent docstrings exported to sphinx.

Nope, we seriously reduced the number of docstrings going into 4.0. Most of them we're outdated and incorrect even before we started working on SL4.

Perhaps waiting for demand for docs is a chicken and egg kind of problem, but as I understand our current maintainers' priorities, documentation is not going to happen all by itself either. Anyone who wants to add some notes, that's super welcome!

@FichteFoll

This comment has been minimized.

Show comment
Hide comment
@FichteFoll

FichteFoll Sep 11, 2018

Contributor

The behavior of setting a value to true or false also isn't documented.
In particular, true adds the setting verbatim without a value, while false doesn't add the setting at all (and als no value, obviously).

Just noticed that falsey values are indeed mentioned. Maybe the exception of 0 could be mentioned, though.

Contributor

FichteFoll commented Sep 11, 2018

The behavior of setting a value to true or false also isn't documented.
In particular, true adds the setting verbatim without a value, while false doesn't add the setting at all (and als no value, obviously).

Just noticed that falsey values are indeed mentioned. Maybe the exception of 0 could be mentioned, though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment