@example or @exampleLink for Component's examples.

[morlay]

Hi guys,

Good news for thinking auto generating docs by the official React team.

And I just started a simple project to do the same thing, but just base on jsdoc to get the and doc json and ui demo.

So if we can set the @example or @exampleLink, that may be useful for the generated the docs.

Thanks. some details we discus here

[fkling]

I'm not sure what exactly you are asking for. If I misunderstood anything, please let me know.

react-docgen doesn't have any opinions about doclets. It will return any prop type or component docblock as is. I.e. if you your component is

/**
 * Some description
 * @example Foo.js
 */
var Component  = React.createClass(...);

you get something like

{
  "description": "Some description\n@example Foo.js",
  "props": {}
}

and you can post-process description to extract any information you want. In fact, react-docgen provides a helper method to extract tags, but you can use any other library of course:

var docgen = require('react-docgen');
var docs = docgen.parse(source);
docs.example = docgen.utils.docblock.getDoclets(docs.description).example;

[morlay]

Thanks, @fkling.

That is cool.

import docgen, { resolver , handlers } from 'react-docgen';
import _ from 'lodash';
import fs from 'fs';

const src = fs.readFileSync(__dirname + 'example/components/Component.js');

const defaultResolver = resolver.findExportedReactCreateClassCall;
const handlers = [
    handlers.propTypeHandler,
    handlers.propDocBlockHandler,
    handlers.defaultPropsHandler,
    handlers.componentDocblockHandler,
    (doc) => {
         // custom handler
        _.forIn(doc['$Documentation_props'], (propObj, propKey)=>{
            _.merge(propObj, docgen.utils.docblock.getDoclets(propObj.description))
        })
    }
];

const docs = docgen.parse(src, defaultResolver,  handlers)

So we can use it is like this ( it is not easy to find the use case without reading the source code. :-) )
However, with this version, we have to put the default resolver and default handlers manually.

And for the custom handler, could we use --handler option to append something to the default handlers?

Then, one more question, for custom resolver. If someone use ES6 module, the two default resolvers will not working. I'm not sure can understand the way to define it clearly. is there more details about it ?

Thanks again.

[fkling]

I really appreciate all the feedback and ideas!

---

So we can use it is like this

You could, but there isn't really a reason to use a custom handler here, since you are not accessing the AST. Post-processing the JS object would be easier.

_.forIn(doc['$Documentation_props'], ...)

While that may work, it assumes specific internal structure of the documentation object. We could add an API that allows to traverse all found props in the documentation object, but I still think that this is better done in a post processing step.

I'm started working on a proposal to make post processing via the CLI easier (that's really WIP, the test cases don't even work/pass). The idea is to simply specific a module which gets passed the resulting JS object.

However, with this version, we have to put the default resolver and default handlers manually.

You can actually pass null as second argument and it will use the default resolver. Regarding the handlers, yeah, maybe we should expose them as an array as well, e.g. docgen.defaultHandlers.

And for the custom handler, could we use --handler option to append something to the default handlers?

Yes, I was thinking about a way to specify handlers from the command line. Maybe with an additional option like --includeDefaultHandlers (but shorter ;)).

If someone use ES6 module, the two default resolvers will not working

Yes, ES6 specificities is not really supported currently. I opened #6 for this particular issue.

I'm not sure can understand the way to define it clearly. is there more details about it ?

Not more than what is written in the readme and the source of the default resolvers. However, I can provide an example. A custom resolver that supports export default .... declarations would look like this:

var resolveToValue = require('../utils/resolveToValue');

function findDefaultExport(ast, recast) {
  var definition;
  recast.visit(ast, {
    visitExportDeclaration: function(path) {
      if (path.node.default) {
        path = resolveToValue(path.get('declaration'));
        if (!isReactCreateClassCall(path)) {
          return false;
        }
        var resolvedPath = resolveToValue(path.get('arguments', 0));
        if (types.ObjectExpression.check(resolvedPath.node)) {
          definition = resolvedPath;
        }
        this.abort();
      }
    }
  return definition;
}

module.exports = findDefaultExport;

Writing custom handlers requires knowledge of recast (or ast-types) and of course about the AST as generated by esprima. I built a web based tool that helps inspecting an AST.

But as I already mentioned, this should be supported by default.

[morlay]

This is so cool. ( And the AST is really new for me ).
A wonderful way to pick doc information from code.

Thanks.

[fkling]

As of v1.1.0, the module now exposes defaultHandlers which, as the name implies, is an array with the default handlers.

[fkling]

Closing this since this was partly addressed and/or farmed out to other issues.