[syntax_tools + doctest] Add some (a lot of) examples to exported functions

[kvakvs]

Changes

• Exported functions in erl_syntax.erl have been visited and some sort of doctest example was added where reasonable.
• Doctest invocation was added to syntax_tools_SUITE

[github-actions]

CT Test Results

  2 files   13 suites   3m 16s ⏱️
122 tests 118 ✅ 4 💤 0 ❌
138 runs  134 ✅ 4 💤 0 ❌

Results for commit 113ae34.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

• Complete CT logs (Download Logs)
• No HTML docs found
• No Windows Installer found

// Erlang/OTP Github Action Bot

[jhogberg]

Thanks for the PR!

I don't think we want this as-is, the vast majority of the added examples don't add anything of value. Can you try to condense them down to the ones you thought were useful? The size makes the PR difficult to review.

[kvakvs]

Thanks for the PR!

I don't think we want this as-is, the vast majority of the added examples don't add anything of value. Can you try to condense them down to the ones you thought were useful? The size makes the PR difficult to review.

In my opinion, those examples, which build language constructs from pieces and demonstrate how they fit together, bring value, and that's at least 3/4 of the examples. Intended for people who didn't work with erl_syntax before to understand how it works, to try and construct something, inviting them to build language tools.

The remaining examples, e.g. setters and getters and debug info, line info, annotations, might have small value, and can be removed.

[jhogberg]

In my opinion, those examples, which build language constructs from pieces and demonstrate how they fit together, bring value, and that's at least 3/4 of the examples.

Please pick one as an example.

[kvakvs]

For example, constructing types (record type)

RTF = erl_syntax:record_type_field(erl_syntax:atom(name), erl_syntax:atom(string)).
RT = erl_syntax:record_type(erl_syntax:atom(person), [RTF]).

or constructing comprehensions with binaries and binary fields

V = erl_syntax:variable("Byte").
BG = erl_syntax:binary_generator(V, erl_syntax:binary([erl_syntax:binary_field(erl_syntax:integer(65))])).
BC = erl_syntax:binary_comp(erl_syntax:binary_field(V), [BG]).

[jhogberg]

Yes, so keep those, and skip the ones that are trivial (e.g. erl_syntax:float/1, erl_syntax:type_application_name/1, or the likes). Showing the result of erl_syntax:type(...) also doesn't bring much value as it's a tautology.

[garazdawi]

Suggested change

```

[garazdawi]

erl_prettypr should really be fixed to insert a space before the &&...

[garazdawi]

Suggested change

```

[garazdawi]

Suggested change

	1> T = erl_syntax:tree(example, [erl_syntax:atom(ok)]).
	2> D = erl_syntax:data(T).
	1> Data = [erl_syntax:atom(ok)].
	2> Tree = erl_syntax:tree(example, Data).
	3> Data =:= erl_syntax:data(Tree).
	true

maybe something like this?