Document 2.x API

[jgaehring]

As a matter of expediency, I may punt on fully documenting the 2.x API in favor of farmOS/field-kit#432, so I'm opening this here for tracking.

Checklist

See notes below for items with questions marks (?).

• README.md
• docs/index.md
  • overview
  • quick start
  • next steps
• docs/schemata.md
  • get
  • set
  • fetch
  • on (?)
  • core_schemata
• docs/metadata.md
  • isUnsynced (?)
  • resolve
• docs/entities.md
  • create
  • update
  • merge
  • fetch
  • send
  • delete
• docs/remotes.md
  • client
    • host
    • clientId
    • getToken
    • setToken
  • authorize
  • setHost
  • info
  • request
  • config (?)
• docs/api.md
  • farmOS
  • model
  • client
  • entities

Undecided methods (?)

on(): I may not document this right away, since I'm mostly using this internally, and not sure I want to expose it.

isUnsynced(): I'd like to remove this and simply add a bool to the remote metadata for this instead.

config(): No such method exists yet, but it's a fairly critical piece of functionality I've implemented in FK as configDocuments which might make sense to include here.

[jgaehring]

I've started a docs branch to start working on this, and I'd like to wrap up the model portions of the docs before moving on to some of the client issues I have queued up next.

I want to hold off on the client/remotes documentation for now, partly b/c I will be adding page and limit options (#42), possibly an id option (#40), modifying the filter option slightly (#33 & #39), and adding some kind of method(s) for retrieving files (#47). But I'm also debating some more significant changes to the remote API, based on how a remote is represented and referenced, i.e., whether there will only ever be a single remote, or if I want to change it to remotes plural to accommodate multiple remotes, potentially.

[jgaehring]

I may also wait on documenting the farm.meta.resolve method. I'm realizing, as I explain the present API, that it's a little strange, and should probably be rethought. Namely, it's a little weird the way it only handles one field at a time, and passes a different array from the one at meta.conflicts. I'm not sure how effective this will be in practice, and it might be worth revisiting when I get to farmOS/field-kit#190.

In any event, I've got a rather terse explanation of the resolve API as it exists now, which will suffice as a placeholder for the time being.

[jgaehring]

isUnsynced(): I'd like to remove this and simply add a bool to the remote metadata for this instead.

I looked at this again, and decided to keep it. Sure, you could just compare changed with lastSync yourself, but there's also a null case to be handled, and I can see implementations changing in the future, whereas a consistent isUnsynced method should can change internally w/o breaking the API.

And I finally got create, update and merge methods documented, which should've been done days ago, but at least they're out of the way before heading into a holiday week. I've merged those changes into main, so I'll pick up the work on the client issues and resume documentation on remote methods when that's done, as I mentioned above. I can also add general API reference at that point.

[jgaehring]

So I took a first pass at using jsdoc-to-markdown to auto-generate an API reference file, based on the JSDoc/TypeScript annotations I've been adding (#25):

https://github.com/farmOS/farmOS.js/blob/0e382a58de6dc0a6441482e8cf358b611ff9a4eb/docs/api.md

The formatting could be greatly improved, but I'm very happy with the amount of coverage this provides. It took some experimentation to get the npm script right (what does it say that neither JSDoc nor jsdoc-to-markdown provide very good docs?), but now that I've got the hang of it, it should be a snap to regenerate api.md whenever there are changes to the API, which should also be easier to catch since we now have type-checking via tsc. Woot!

[jgaehring]

All done with the docs, as of c2302d7. Just final touches now for the beta release! 🎉