Improve documentation of vmod_saintmode

[denisbr]

Changed the backend example to reflect the real usage of this method. Added some comments and a bit of text in an attempt to explicitly convey how the logic works.

[lkarsten]

Hi.

I've put in most of this in master now. I don't think removing the reference documentation for .bcakend() and replacing it with an example is an improvement, and skipped that part.

Maybe we should have a section for a "complete/copy&pasteable example in the top of all .vcc files?

When we get into the specific functions/methods they tend to depend on setup from other functions, which makes the example value of the reference either long and repeating or incomplete.

[denisbr]

@lkarsten Ok, the reason why I wanted to alter the reference documentation for .backend is (as discussed) it only serves to confuse the real use of it. You would likely never use it in vcl_backend_fetch at all, and also never to assign a backend directly like that reference doc does.

[fgsch]

@denisbr the usage in v_b_f{} is correct. The issue here is using the saintmode backend directly, which is not incorrect but as I mentioned before not very useful.

[denisbr]

@fgsch If you want to use vmod_saintmode in the real world, you use minumum 2 saintmode backends in a director, and then in v_b_f{} assign a backend from the director, not from the saintmode backend. That's why I claim that, while it'll compile, the reference VCL is confusing and as you say not useful. I would expect the reference to show how it's meant to be used, not a misleading usage ;)

[fgsch]

@denisbr my first comment was referring to "You will likely never use it in vcl_backend_fetch at all". Anwyay, I agree with you.