foam-framework / foam

Feature-Oriented Active Modeller
Apache License 2.0
787 stars 55 forks source link

Some things need fixing in the "DAO User Guide" #524

Open mdittmer opened 8 years ago

mdittmer commented 8 years ago

Explication of the Sink interface reads "remove()"; should be "remove(obj)".

Long-form description of "put(obj, sink)" does not discuss the error case.

"NB" in long-form description of "remove(objOrId, sink)" should clarify whether or not the "remove(obj)" callback is called when no such object exists in the DAO. It should also mention what the value of "obj" will be in this case.

In long-form description of "select(sink, options)", we say that the Future is resolved "at the same time as sink.eof() is called". This statement is ambiguous in a single-threaded Javascript world. We need to document which one is actually called first (or else mention that either order is acceptable).

Long-form description of "removeAll(sink, options)" should briefly describe which callbacks are called when. Is it a sequence of "remove(obj)"s, potentially halted early by a call to "error(error)"?

In long-form description of "listen(sink, options)" we use the example "myDAO.where(...).listen()", then refer to the "query". Perhaps the example code should contain "where(query)".

Does "pipe(sink, options)" issue an "eof()" after the select-part, before the listen-part?

Suggest removing "infinite" from "infinite scrolling".