Incomplete example in documentation

[AndreaCrotti]

The first example in the documentation (friends-of) leave the friends-of implementation empty, but it also doesn't mention anywhere what kind of object it should return.

In the end I found out it just has to be a value wrapped in urania.core/value but I guess it would be nice to have a fully working example in the docs to try out. I can make a PR if that's useful I made up a working example.

[oliyh]

Hi Andrea,

I guess that's true in section 3.1, but this is labelled Rationale and I guess it's trying to show the outline of the code to give you the idea and not be complicated by implementation details. The implementation is provided in the next two sections 3.2 and 3.3 to give you some working code.

Perhaps instead of ;; ... it should say ;; todo: implement (see below) or similar?

Cheers

[AndreaCrotti]

Yeah well imho the fact that it's doing a remote request is not even entirely necessary.. We could just show in the first example something like (u/value #{"friend" "friend2"}) which makes it work already and make it clear what kind of return type is expected, which was the thing that wasn't exactly clear imho.

Also documenting simply what type should be returned could be enough otherwise.

[oliyh]

u/value might be misleading though in this instance because it would be in effect stubbing the remote fetch. For a remote fetch you want a DataSource, so perhaps ;; todo: return a DataSource (see below) which would guide the reader to learn about DataSource in the next section?

[AndreaCrotti]

Yeah that could be enough sure I can do that