wp-source: better api docs

[juanmaguitar]

Added API docs for every method and Table of Contents

[luisherranz]

Great job! 👏

I've added some comments below. I'm aware that some of the errors are previous to this PR, but let's take this opportunity to improve them 🙂

[luisherranz]

Actions don't return data. Data is always accessed via the state.

That's because Frontity is following the Flux pattern, like Redux.

[luisherranz]

Using promises with .then is pretty much deprecated in favor of async/await nowadays. I'd rather show examples using await:

const response = await api.get({
  endpoint: "posts",
  params: { _embed: true, categories: "2,3,4" },
});

[juanmaguitar]

Using promises with .then is pretty much deprecated in favor of async/await nowadays. I'd rather show examples using await:

I'm not sure about this.

• I don't agree with the affirmation than the use of .then is deprecated
• The use of await alone doesn't work unless you use inside of an async function

Using then in the examples makes them ready to be "copied & pasted" while still indicates the nature of a Promise

[luisherranz]

By deprecated I mean it's not used any more thanks to the async/await functions.

We (you and me) are used to it because we had to learn it before async/await existed. But for JS newbies the .then prop is really confusing. If you think about it, it's quite a horrible API compared to async/await.

[juanmaguitar]

I think you're right 👍

[luisherranz]

I don't think the return value should be simply Promise. It needs to contain a reference to the value that the promise resolves to, which is the useful information for the developer.

In this case the promise resolves to a Response object from fetch: https://developer.mozilla.org/en-US/docs/Web/API/Response

[luisherranz]

I've added a couple of details but it looks perfect to me 🙂

[luisherranz]

This endpoint doesn't exist anymore because it belongs to our old plugin which is now deprecated. I don't know why this example is here, I guess we added it at the very beginning.

I would use another example, something that is used today. For example, the /acf/v3/posts endpoint.

[luisherranz]

Maybe this information should be in the "Learning Frontity - Actions" section?

Apart from that, maybe it's worth mentioning that, even though actions don't return data, they return a promise that resolves when the action is finished.

You can do something like this:

await actions.source.fetch("/some-post");

which is useful when you need to access the new state just after calling the action:

await actions.source.fetch("/some-post"); // <- Wait until we fetch "/some-post".
const somePost = state.source.get("/some-post"); // <- The data will exist.

This is of course not needed on React components, because:

• They are not async (you cannot use await).
• They re-render when the state accessed changes.

const SomePost = ({ actions, state }) => {
  useEffect(async () => {
    // You can use await here if you pass an async function, but it's not required.
    await actions.source.fetch("/some-post");
  }, []);

  // The data will not exist at first, `data.isReady` will be false.
  // But then, it will rerender when `actions.source.fetch` is finished.
  const somePost = state.source.get("/some-post");

  // This will work just fine.
  return somePost.isReady ? <Post link="/some-post" /> : <Loading />;
};

What do you think?

[luisherranz]

Nice 🙂

I don't know if the /acf/v3/posts endpoint accepts a slug parameter but I guess it's not important.

I've added an additional commit to replace route with link in all the references where route was deprecated. I don't understand why we forgot to update this when we did the change.

The commit introduced a lot of format changes due to prettier. Let's discuss how to solve that in https://community.frontity.org/t/code-documentation-workflow/1633.