Skip to content

Commit

Permalink
[Docs] Expand API parsing and rendering
Browse files Browse the repository at this point in the history 
The `Animated` module exposes a lot of functionality, including internal
classes. This diff extracts properties and classes from modules and renders them
recursively.

This also adds `Animated` to the autogen docs now that they more capable,
although it needs way more docblocks and such which will come later.
  • Loading branch information
@sahrens
sahrens committed Sep 1, 2015
1 parent 1a411a7 commit 126928b
Show file tree
Hide file tree
Showing 3 changed files with 124 additions and 50 deletions.
29 changes: 21 additions & 8 deletions website/jsdocs/jsdocs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ var genericTransform = require('./generic-function-visitor');
var genericVisitor = genericTransform.visitorList[0];
var traverseFlat = require('./traverseFlat');
var parseTypehint = require('./TypeExpressionParser').parse;
var util = require('util');

// Don't save object properties source code that is longer than this
var MAX_PROPERTY_SOURCE_LENGTH = 1000;
Expand Down Expand Up @@ -317,6 +318,7 @@ function getObjectData(node, state, source, scopeChain,
commentsForFile, linesForFile) {
var methods = [];
var properties = [];
var classes = [];
var superClass = null;
node.properties.forEach(function(property) {
if (property.type === Syntax.SpreadProperty) {
Expand All @@ -341,7 +343,8 @@ function getObjectData(node, state, source, scopeChain,
scopeChain
);
if (expr) {
if (expr.type === Syntax.FunctionDeclaration) {
if (expr.type === Syntax.FunctionDeclaration ||
expr.type === Syntax.FunctionExpression) {
var functionData =
getFunctionData(expr, property, state, source, commentsForFile,
linesForFile);
Expand All @@ -362,23 +365,32 @@ function getObjectData(node, state, source, scopeChain,
}
var docBlock = getDocBlock(property, commentsForFile, linesForFile);
/* CodexVarDef: modifiers, type, name, default, docblock */
var propertyData = [
['static'],
'',
if (property.value.type === Syntax.ClassDeclaration) {
var type = {name: property.value.id.name};
var classData = getClassData(property.value, state, source, commentsForFile, linesForFile);
classData.ownerProperty = property.key.name;
classes.push(classData);
} else {
var type = {name: property.value.type};
}
var propertyData = {
// Cast to String because this can be a Number
// Could also be a String literal (e.g. "key") hence the value
String(property.key.name || property.key.value),
name: String(property.key.name || property.key.value),
type,
docblock: docBlock || '',
source: source.substring.apply(source, property.range),
modifiers: ['static'],
propertySource,
docBlock || '',
property.loc.start.line
];
};
properties.push(propertyData);
break;
}
});
return {
methods: methods,
properties: properties,
classes: classes,
superClass: superClass
};
}
Expand Down Expand Up @@ -410,6 +422,7 @@ function getClassData(node, state, source, commentsForFile, linesForFile) {
}
});
var data = {
name: node.id.name,
methods: methods
};
if (node.superClass && node.superClass.type === Syntax.Identifier) {
Expand Down
142 changes: 101 additions & 41 deletions website/layout/AutodocsLayout.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,53 +20,52 @@ var slugify = require('slugify');

var styleReferencePattern = /^[^.]+\.propTypes\.style$/;

var ComponentDoc = React.createClass({
renderType: function(type) {
if (type.name === 'enum') {
if (typeof type.value === 'string') {
return type.value;
}
return 'enum(' + type.value.map((v => v.value)).join(', ') + ')';
function renderType(type) {
if (type.name === 'enum') {
if (typeof type.value === 'string') {
return type.value;
}
return 'enum(' + type.value.map((v) => v.value).join(', ') + ')';
}

if (type.name === 'shape') {
return '{' + Object.keys(type.value).map((key => key + ': ' + this.renderType(type.value[key]))).join(', ') + '}';
}
if (type.name === 'shape') {
return '{' + Object.keys(type.value).map((key => key + ': ' + renderType(type.value[key]))).join(', ') + '}';
}

if (type.name == 'union') {
return type.value.map(this.renderType).join(', ');
}
if (type.name == 'union') {
return type.value.map(renderType).join(', ');
}

if (type.name === 'arrayOf') {
return '[' + this.renderType(type.value) + ']';
}
if (type.name === 'arrayOf') {
return '[' + renderType(type.value) + ']';
}

if (type.name === 'instanceOf') {
return type.value;
}
if (type.name === 'instanceOf') {
return type.value;
}

if (type.name === 'custom') {
if (styleReferencePattern.test(type.raw)) {
var name = type.raw.substring(0, type.raw.indexOf('.'));
return <a href={slugify(name) + '.html#style'}>{name}#style</a>
}
if (type.raw === 'EdgeInsetsPropType') {
return '{top: number, left: number, bottom: number, right: number}';
}
return type.raw;
if (type.name === 'custom') {
if (styleReferencePattern.test(type.raw)) {
var name = type.raw.substring(0, type.raw.indexOf('.'));
return <a href={slugify(name) + '.html#style'}>{name}#style</a>
}

if (type.name === 'stylesheet') {
return 'style';
if (type.raw === 'EdgeInsetsPropType') {
return '{top: number, left: number, bottom: number, right: number}';
}
return type.raw;
}

if (type.name === 'func') {
return 'function';
}
if (type.name === 'stylesheet') {
return 'style';
}

return type.name;
},
if (type.name === 'func') {
return 'function';
}
return type.name;
}

var ComponentDoc = React.createClass({
renderProp: function(name, prop) {
return (
<div className="prop" key={name}>
Expand All @@ -77,7 +76,7 @@ var ComponentDoc = React.createClass({
{name}
{' '}
{prop.type && <span className="propType">
{this.renderType(prop.type)}
{renderType(prop.type)}
</span>}
</Header>
{prop.type && prop.type.name === 'stylesheet' &&
Expand Down Expand Up @@ -128,7 +127,7 @@ var ComponentDoc = React.createClass({
{name}
{' '}
{style.props[name].type && <span className="propType">
{this.renderType(style.props[name].type)}
{renderType(style.props[name].type)}
</span>}
</h6>
</div>
Expand Down Expand Up @@ -190,7 +189,6 @@ var ComponentDoc = React.createClass({
<Marked>
{content.description}
</Marked>

<HeaderWithGithub
title="Props"
path={content.filepath}
Expand Down Expand Up @@ -264,7 +262,6 @@ var APIDoc = React.createClass({
);
},


renderMethods: function(methods) {
if (!methods.length) {
return null;
Expand All @@ -281,6 +278,67 @@ var APIDoc = React.createClass({
);
},

renderProperty: function(property) {
return (
<div className="prop" key={property.name}>
<Header level={4} className="propTitle" toSlug={property.name}>
{property.name}
{property.type &&
<span className="propType">
{': ' + renderType(property.type)}
</span>
}
</Header>
{property.docblock && <Marked>
{this.removeCommentsFromDocblock(property.docblock)}
</Marked>}
</div>
);
},

renderProperties: function(properties) {
if (!properties || !properties.length) {
return null;
}
return (
<span>
<H level={3}>Properties</H>
<div className="props">
{properties.filter((property) => {
return property.name[0] !== '_';
}).map(this.renderProperty)}
</div>
</span>
);
},

renderClasses: function(classes) {
if (!classes || !classes.length) {
return null;
}
return (
<span>
<div>
{classes.filter((cls) => {
return cls.name[0] !== '_' && cls.ownerProperty[0] !== '_';
}).map((cls) => {
return (
<span key={cls.name}>
<Header level={2} toSlug={cls.name}>
class {cls.name}
</Header>
<ul>
{this.renderMethods(cls.methods)}
{this.renderProperties(cls.properties)}
</ul>
</span>
);
})}
</div>
</span>
);
},

render: function() {
var content = this.props.content;
if (!content.methods) {
Expand All @@ -294,6 +352,8 @@ var APIDoc = React.createClass({
{this.removeCommentsFromDocblock(content.docblock)}
</Marked>
{this.renderMethods(content.methods)}
{this.renderProperties(content.properties)}
{this.renderClasses(content.classes)}
</div>
);
}
Expand Down Expand Up @@ -371,7 +431,7 @@ var Autodocs = React.createClass({
var docs = JSON.parse(this.props.children);
var content = docs.type === 'component' || docs.type === 'style' ?
<ComponentDoc content={docs} /> :
<APIDoc content={docs} />;
<APIDoc content={docs} apiName={metadata.title} />;

return (
<Site section="docs" title={metadata.title}>
Expand Down
3 changes: 2 additions & 1 deletion website/server/extractDocs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -134,7 +134,7 @@ function renderAPI(type) {
try {
json = jsDocs(fs.readFileSync(filepath).toString());
} catch(e) {
console.error('Cannot parse file', filepath);
console.error('Cannot parse file', filepath, e);
json = {};
}
return componentsToMarkdown(type, json, filepath, n++);
Expand Down Expand Up @@ -187,6 +187,7 @@ var components = [
var apis = [
'../Libraries/ActionSheetIOS/ActionSheetIOS.js',
'../Libraries/Utilities/AlertIOS.js',
'../Libraries/Animated/Animated.js',
'../Libraries/AppRegistry/AppRegistry.js',
'../Libraries/AppStateIOS/AppStateIOS.ios.js',
'../Libraries/Storage/AsyncStorage.ios.js',
Expand Down

0 comments on commit 126928b

Please sign in to comment.