Documentation suggestions about Terms

[GunArm]

Apologies for the long winded issue here but I don't know how else to convey an "experience", than telling the story:

I am trying to make a Parlot parser tag for Fluid but really struggled with the docs as they exist.

Initially I was trying to use Deane Barker's documentation (https://deanebarker.net/tech/fluid/parser-tags-blocks/) which says:

Parlot has several pre-built parsers in the Terms static class.

var connectionString = Terms.NonWhiteSpace();
var sql = Terms.String();
var optionalCssClass = ZeroOrOne(Terms.NonWhiteSpace());

and shows them combined:

var sqlTagParser =
  connectionString
  .And(sql)
  .And(optionalCssClass);

But there is no Terms static class.  For over a day I was trying to explore intellisense, manually adding Parlot through nuget, other experiments, etc, trying figure out what I was missing to make this example work, until I eventually gave up and moved onto a different aspect of my project.
Eventually I came back to it, and I decided that those docs must just be out of date or for an old version (although they're linked to in the Fluid Readme...).  Exploring intellisense blindly I found a TermsBuilder class and by experimenting I figured out I could use an instance of that place of the missing Terms static class:

TermsBuilder foo = new TermsBuilder();
var connectionString = foo.NonWhiteSpace();
var sql = foo.String();
var optionalCssClass = ZeroOrOne(foo.NonWhiteSpace());

I assumed this was supposed to be the "new" syntax, although ZeroOrOne also doesn't work as written and it's unclear if that's meant to be a local instance method which is in the local context of the example code but simply not shown, or if it's some kind of class constructor from Fluid/Parlot, etc.  I did find there is a class ZeroOrOne, but the constructor is just a bit away from how that's written.
I then found the actual Parlot docs here: https://github.com/sebastienros/parlot
And I saw that the example there also use Terms as if it's a static class.

var divided = Terms.Char('/');
var times = Terms.Char('*');
var minus = Terms.Char('-');
var plus = Terms.Char('+');
var openParen = Terms.Char('(');
var closeParen = Terms.Char(')');

Somewhere (can't find it now) I saw reference to a Literals "thing" that seems like it might be useful but similar to Terms I couldn't find anywhere.

I'm thinking "is it possible that both Deane's docs and Parlots official docs are both showing examples of an interface that no longer exists?"  I assumed, weird as it would be, that must be the case, because no such static classes exist, and I really, really looked...

Trying to make sense of this I got into the source code to go through the change history and see "how long ago the interface that the docs use was taken away".

In the source I stumbled onto Parlot/Fluid/Parsers.cs which has a Terms and Literals accessor defined at the top.  I started trying to do this:

var connectionString = Parsers.Terms.NonWhiteSpace();
var sql = Parsers.Terms.String();
var optionalCssClass = ZeroOrOne(Parsers.Terms.NonWhiteSpace());

But ZeroOrOne constructor still doesn't work (atleast not like that) because the class ctor needs second argument for a default value (I can add that but I'm so new to this I'm trying to get examples to work before improvising).  I also saw that in many classes in the source it's actually referring to Terms without Parsers. prefix, and that really threw me until I finally noticed at the top of the source files:

using static Parlot.Fluent.Parsers;

This is what I was missing the whole time. It also makes ZeroOrOne resolve, because that's a static method, with the same name as the class I thought it was meant to be.

---

My goal is not to whine or tell a sob story, but to convey the effect that I spent over a week going back and forth between attempts, confusion, exploration, feeling like I'm in an alternate universe, giving up, coming back, speculation, looking for other docs, diving the source, etc, before finally figuring this out.

It seems like a really silly thing but as a new person approaching the available examples, honestly, it really put me through the ringer.

It's not mentioned in any of the docs adjacent to things where it is being implicitly assumed to be there.  Deane's docs specifically call Terms a "static class" rather than "a static accessor to an instance of the TermsBuilder class, on the Parsers class" or something.

It's tricky because when you try to implement one of these examples, intellisense can never give you any assistance either, since it can recommend usings for namespaces you need, but not importing static class functions (or it never did for me atleast).  Also, I've done good deal of c#, and we all have our bubbles, but importing static functions like that is something I don't see often and never even considered during this, but maybe that's my deficiency.

I did just now notice that on the Parlot readme, above the code block, there is a link to the same code, which does show that at the top, but no attention is drawn to the fact of how important it is.  I kinda just clicked that link and saw that it's almost exactly what was in the readme and moved on.

All of this to say, it might save someone in the future a lot of headache if the need to import this static class was mentioned in the readme for Parlot. And if Deane sees this, in his Fluid doc on parser tags. And maybe it is in some place that I totally missed, but maybe it could be in more places, or more prominent.

Final note: Thank you very much for Palrot and Fluid. And thank you Deane for your Fluid docs. I don't mean to dish on anyone.