Ability to auto-generate docunentation

[greim]

I'd like to auto-generate documentation based on the information passed to Router.createClass(); showing which nodes and operations are available. Something along the lines of this:

users
|--create (callable with (username, email))
`--:id
   |--destroy (callable)
   |--:prop => properties of a user (read/write)
   |--avatar => reference to media[:id] (read/write)
   |--is_following
   |  `--:otherId => boolean (read/write)
   |--followers
   |  |--:index => reference to users[:id] (readonly)
   |  `--length => integer gte 0 (readonly)
   |--followees
   |  |--:index => reference to users[:id] (readonly)
   |  `--length => integer gte 0 (readonly)
   `--follow (callable with (otherId))
...etc

...where tokens like :id indicate a wildcard capture pattern in the router like {keys:id}. Does that make sense?

This would help devs on my team start using Falcor without needing to constantly check the source code. Has work been done along these lines? If not, I don't mind diving into it myself, but I'd need hooks into the router to extract this info, and/or a way to annotate routes (e.g. to declare return types shown above as => ...).

Or, I could do this completely independently if only there was a way to parse a route pattern string into an AST?

[trxcllnt]

@greim take a look at the falcor-path-syntax project, it's the lib that parses the string syntax to Arrays. The Router calls parse with extendedRules = true, so it adds extra metadata to the parsed indexer tokens. You can run the following example in esnextb.in to see how it parses different routes:

import parse from 'falcor-path-syntax';

const route = parse('path.to[{keys:values}]', true);

console.clear();

route.forEach((key) => {
  if (typeof key === 'string') {
    console.log(`key: ${key}`);
  } else if (key.named === true) {
    console.log(`routed key: ${JSON.stringify(key)}`);
  }
});
/* prints
key: path
key: to
routed key: {"type":"keys","named":true,"name":"values"}
*/

[greim]

Cool, this will be my starting point. Thanks for the quick response!

[trxcllnt]

@greim I will need this and may have some free cycles soon, have you started and/or are you interested in collaborating on a route documentation generator we can all use?

[greim]

Yes I'd be open to collaboration. I have something very crude up and running already; getting ASTs for the route patterns was the biggest hurdle :) Basically it's a thin wrapper around FalcorRouter.createClass() that takes the same args:

import router from 'modules/self-documenting-router';
var MyRouter = router.createClass([ ...all my routes... ]);
var descriptor = MyRouter.descriptor();

MyRouter is just a regular Falcor router class but with a .descriptor() function. descriptor is a JSON object which I then make available via a koa endpoint. Elsewhere, a React component fetches it and renders it into this:

One of my goals was to have return types for each route which required adding metadata to route objects:

{
  route: 'users[{keys:id}].user_followee_list[{ranges:index}]',
  returns: 'references into ["users", id]', // <-- added this
  get() { ... }
}

Anyway let me know if any of this fits with what you need.

[trxcllnt]

@greim that's already more than I was expecting, so thanks for the effort. Is there a public repo yet? We should probably move this discussion over there.

[greim]

Cool. I'll lift this code out into a separate repo and ping you back once it's ready. Might take a multiple days depending on how busy I get.

[ludovicthomas]

@greim Have you released something about this documentation tool? Thanks

[greim]

Yes, here it is. https://github.com/greim/falcor-doc-router