colinkiama / vala-lint-vscode Goto Github PK

I'd like to suggest to add some helpful documentation (i.e. a more complete setup) to the README, because perhaps it may be the first thing people find when searching for a linter for vscode, before the vala linter in general itself, and if they install it without success, they may simply give up, thinking it was a small project anyway, it's incomplete or abandoned. (Well, I considered each of those, when I questioning myself if I should continue searching.)

When I first saw this extension, I only saw one contributor, so I expected some basic linting, on top of the linter dependency. I did see the second dependency clearly, but I thought it was a lame self reference to this project - forgive my wording. As I expected to end up on the same page as I already was, I didn't click it for a long time. However, I'm stubborn, and eventually found out there is another project, the vala linter project, but not everyone is. If they give up having it installed properly, they encounter a worse Vala-experience and it won't help attracting new comers, like myself.

Finally at the linter project, I've discovered to install the vala linter through their dockerfile, but not successfully yet, and I'm awaiting a response to my issue there.

Setup

So, again, it would be useful if the README contained a guide with the following steps.

1. A setup of the vala lint for the operating system, with an additional reference to their setup (# docker) for possibly updated methods. Also, it should be made more apparent that the second dependency when it'll be mentioned is a distinct project, which already happen in the first phrase of the README, but at the moment, there is no explanation on what vala-lint is, and just that on its own would have made me realize it's really something else.

2. A test to verify the linter is well installed and accessible through the $PATH variable, before advancing to the next step.

3. A verification of whether the vscode extension is working properly

   1. perhaps with a code example. Also, direct the programmer to the output window. I discovered it by accident, because I thought from the README of linter, that it could only be accessed through debugging the extension!

   2. Explicitely tell them this is not what they should encounter.

   Searched for any of io.elementary.vala-lint; couldn't be found within $PATH: [
       "/home/vendillah/.local/bin",
       "...",
   ]
   

   and what they should see instead. (I'm not sure about it, as it doesn't work for me.) As a fun fact: when I first got to see this "couldn't be found" message, I thought it made no sense, as I had both vala and valac installed in .local/bin, because at that time, I had not discovered the vala-lint project yet.
   

   3. And so on, showing the discovered linting options for the code example.

   4. A clarification of what we should be seeing (change) here at what time. Should the run time status be different than this? I would think so, but
      

Build, Modify, Commit

It's also useful to have some general information on how to contribute (i.e., how to setup the development environment of the extension, or where to get started).

Next to that, explaining how the linter works and how it's being used may help attracting contributors, which is necessary for when you perhaps decide to stop working on maintaining this extension.

Currently, the user has no indication that there are any issues with vala-lint. It makes it seem like the extension isn't working.