Help me understand how diagnostics work

[niderhoff]

From the help I found the following paragraph about the diagnostics display:

By default, Neo-tree will display diagnostic symbols next to files. It will
display the highest severity level for files, and errors only for directories.

What is meant with "display the highest severity level for files" ? Highest severity in relation to what? I don't understand it really.

In the defaults.lua I can see the following code that was mentioned in #853

renderers = {
    directory = {
      { "indent" },
      { "icon" },
      { "current_filter" },
      {
        "container",
        content = {
          { "name", zindex = 10 },
          {
            "symlink_target",
            zindex = 10,
            highlight = "NeoTreeSymbolicLinkTarget",
          },
          { "clipboard", zindex = 10 },
          { "diagnostics", errors_only = true, zindex = 20, align = "right", hide_when_expanded = true },
          { "git_status", zindex = 10, align = "right", hide_when_expanded = true },
          { "file_size", zindex = 10, align = "right" },
          { "type", zindex = 10, align = "right" },
          { "last_modified", zindex = 10, align = "right" },
          { "created", zindex = 10, align = "right" },
        },
      },
    },

especially the line

          { "diagnostics", errors_only = true, zindex = 20, align = "right", hide_when_expanded = true },

What exactly is the purpose of errors_only and what is it supposed to do? It seems like it will show errors only and other diagnostics are hidden? But for me that is is not really in line with what the help is saying in the quote above.

Can you help me understand what is the purpose of this flag and how in general the diagnostics are supposed to behave?

I am trying to figure this out, because I want only errors to be shown, but on my system it shows errors and warnings.

The severity level for the given line is '2':

:lua print(vim.inspect(vim.diagnostic.get(0, {lnum = vim.fn.line(".")-1})))                                                                                                                                                                                     
{ {                                                                                                                                                                                                                                                             
    _tags = {                                                                                                                                                                                                                                                   
      deprecated = true                                                                                                                                                                                                                                         
    },                                                                                                                                                                                                                                                          
    bufnr = 2,                                                                                                                                                                                                                                                  
    code = "deprecated",                                                                                                                                                                                                                                        
    col = 55,                                                                                                                                                                                                                                                   
    end_col = 61,                                                                                                                                                                                                                                               
    end_lnum = 353,                                                                                                                                                                                                                                             
    lnum = 353,                                                                                                                                                                                                                                                 
    message = "Deprecated.(Defined in Lua 5.1/LuaJIT, current is Lua 5.4.)",                                                                                                                                                                                    
    namespace = 27,                                                                                                                                                                                                                                             
    severity = 2,                                                                                                                                                                                                                                               
    source = "Lua Diagnostics.",                                                                                                                                                                                                                                
    user_data = {                                                                                                                                                                                                                                               
      lsp = {                                                                                                                                                                                                                                                   
        code = "deprecated",                                                                                                                                                                                                                                    
        data = {                                                                                                                                                                                                                                                
          versions = { "Lua 5.1", "LuaJIT" }                                                                                                                                                                                                                    
        },                                                                                                                                                                                                                                                      
        message = "Deprecated.(Defined in Lua 5.1/LuaJIT, current is Lua 5.4.)",                                                                                                                                                                                
        range = {                                                                                                                                                                                                                                               
          ["end"] = {                                                                                                                                                                                                                                           
            character = 61,                                                                                                                                                                                                                                     
            line = 353                                                                                                                                                                                                                                          
          },                                                                                                                                                                                                                                                    
          start = {                                                                                                                                                                                                                                             
            character = 55,                                                                                                                                                                                                                                     
            line = 353                                                                                                                                                                                                                                          
          }                                                                                                                                                                                                                                                     
        },                                                                                                                                                                                                                                                      
        severity = 2,                                                                                                                                                                                                                                           
        source = "Lua Diagnostics.",                                                                                                                                                                                                                            
        tags = { 2 }                                                                                                                                                                                                                                            
      }                                                                                                                                                                                                                                                         
    }                                                                                                                                                                                                                                                           
  } }