Psalm: Improve documentation

[andreasschroth]

First of all, thank you very much for this project, I like it a lot! 👍I can also see that this is continually improved and feedback is appreciated here.

I want to suggest that this project gets an improved documentation.

Why? Because a good documentation helps everyone who looks into this tool and eases getting started with it. It's also useful for wider adoption. Many developers will just skip tools that have no good documentations or that doesn't seem to provide quick solutions for their problems.

What would I add? This is a non-complete list, just from what I saw, that imo, should be added:

• List of all available analysis performed, including a short description and code examples.
• How many levels are there for analysing? What's the highest level, what's the max. level? Which checks are performed at each level?
• I noticed that just very recently a phar has been added; that should be mentioned in the docs as well, not just composer.
• Common tasks many devs want to achieve:
  
  
  
  • Suppressing a specific check completely on the project (I found explanations for specific files, functions or even lines, but not how to disable a specific check in a whole project; might for example be useful for CI to get started with the tool and then activate more and more rules).
  
  
  • Adding multiple code folders to the psalm.xml config.
  
  
  • Full documentation of all supported config settings. What's totallyTyped good for?
  
  

Sorry, I hope I'm not being too critical here and yes, sure, it's easy to find out about those things by just searching the source code of this repository, you can see which levels there are provided and what they include, etc. But especially beginners will appreciate a proper documentation a lot I think. Unfortunately, often especially the best projects out there seem to treat the documentation as "not so important" or "something you must provide somehow, because everyone expects it, but nobody really wants to write it". I hope my feedback was useful somehow! Keep up the good work. 👍

[muglug]

I agree that the documentation can be improved – that you're asking about it means the discoverability is lacking. A lot of the answers to your questions exist already.

List of all available analysis performed, including a short description and code examples

More than what's listed here?

How many levels are there for analysing? What's the highest level, what's the max. level? Which checks are performed at each level?

Good point, will link to the config levels in the assets folder explicitly

I noticed that just very recently a phar has been added; that should be mentioned in the docs as well, not just composer.

Agreed!

Suppressing a specific check completely on the project

Dealing with code issues contains a section about the project-wide XML - but I agree this can be more explicit

Full documentation of all supported config settings. What's totallyTyped good for?

That lives here

[andreasschroth]

Now I feel a bit embarrassed, but I actually didn't realise that there's a doc folder existing....... 😨

So maybe it would be a good idea then to just link all the available docs directly in the README.md like a separate section Documentation? Like an overview?

[muglug]

https://github.com/vimeo/psalm/blob/master/docs/index.md is linked from the readme, but it should be more explicit

[andreasschroth]

Well, I'm sorry for overlooking the links on the README.md, but I think the main problem is how it is structured. The links are placed where I just wouldn't expect them at all.

I expect a introduction documentation like the README.md to first provide me with first steps, quick start, etc. and then, at the end, with a list like Further Reading or More Documentation and then all available documentation in a list.

Right now, that's why I overlooked it probably, first the links are placed (not even in single sentences or a list, but just in one line) and even before the Quickstart Guide.

[muglug]

I've made that documentation explicit in the Readme

[ostrolucky]

What's the highest level, what's the max. level?

This. Major issue with Psalm I had was that I did not realize level 1 is most strict as opposed to least strict. This is contrary to levels in PHPStan.

Second big issue I had was that default settings make screen fill with INFOs. I did not realize at first these are not actual errors and can be suppressed by --show-info=false. Maybe it's just me, but I would rather see those suppressed by default in lenient levels, or told about --show-info=false in getting started.

[muglug]

@ostrolucky agree with --show-info=false. Psalm now gives instructions about how to remove those in its output:

[muglug]

I've added a dedicated docs page on Psalm's website: https://getpsalm.org/docs

Feel free to let me know if there are areas that are unclear!