diff --git a/README.rst b/README.rst index 864b4329..651962ea 100644 --- a/README.rst +++ b/README.rst @@ -65,12 +65,12 @@ Setup Use === -In short, use the directives below, then build your Sphinx docs by running ``make html`` in your docs directory. (If you have never used Sphinx or written reStructuredText before, here is `where we left off in its tutorial `_. For a quick start, just add things to index.rst for now.) +In short, write a folder full of reStructuredText files, use the following directives to pull in your JSDoc documentation, then tell Sphinx to render it all by running ``make html`` in your docs directory. If you have never used Sphinx or written reStructuredText before, here is `where we left off in its tutorial `_. For a quick start, just add things to index.rst for now. autofunction ------------ -Document your JS code using standard JSDoc formatting:: +First, document your JS code using standard JSDoc formatting:: /** * Return the ratio of the inline text length of the links in an element to @@ -87,20 +87,18 @@ Document your JS code using standard JSDoc formatting:: return (length - lengthWithoutLinks) / length; } -Our directives work much like Sphinx's standard autodoc ones. You can specify -just a function's name... :: +Then, reference your documentation using sphinx-js directives. Our directives work much like Sphinx's standard autodoc ones. You can specify just a function's name... :: .. js:autofunction:: someFunction ...and a nicely formatted block of documentation will show up in your docs. -Or you can throw in your own explicit parameter list, if you want to note +You can also throw in your own explicit parameter list, if you want to note optional parameters:: .. js:autofunction:: someFunction(foo, bar[, baz]) -You can even add additional content. If you do, it will appear just below any -extracted documentation:: +You can even add additional content. If you do, it will appear just below any extracted documentation:: .. js:autofunction:: someFunction @@ -118,6 +116,10 @@ extracted documentation:: .. js:autofunction:: someClass#someFunction :short-name: +``autofunction`` can also be used on callbacks defined with the `@callback tag `_. + +There is experimental support for abusing ``autofunction`` to document `@typedef tags `_ as well, though the result will be styled as a function, and ``@property`` tags will fall misleadingly under an "Arguments" heading. Still, it's better than nothing until we can do it properly. + autoclass --------- @@ -259,8 +261,11 @@ Run ``python setup.py test``. Run ``tox`` to test across Python versions. Version History =============== -Unreleased +2.2 + * Add ``autofunction`` support for ``@callback`` tags. (krassowski) + * Add experimental ``autofunction`` support for ``@typedef`` tags. (krassowski) * Add a nice error message for when jsdoc can't find any JS files. + * Pin six more tightly so ``python_2_unicode_compatible`` is sure to be around. 2.1 * Allow multiple folders in ``js_source_path``. This is useful for gradually migrating large projects, one folder at a time, to jsdoc. Introduce ``root_for_relative_js_paths`` to keep relative paths unambiguous in the face of multiple source paths. diff --git a/sphinx_js/renderers.py b/sphinx_js/renderers.py index eb8e4b0a..39ed9108 100644 --- a/sphinx_js/renderers.py +++ b/sphinx_js/renderers.py @@ -118,6 +118,7 @@ def _fields(self, doclet): """ FIELD_TYPES = OrderedDict([('params', _params_formatter), + ('properties', _params_formatter), ('exceptions', _exceptions_formatter), ('returns', _returns_formatter)]) for field_name, callback in iteritems(FIELD_TYPES): @@ -168,7 +169,7 @@ def _members_of(self, full_path, include, exclude, should_include_private): """ def rst_for(doclet): - renderer = (AutoFunctionRenderer if doclet.get('kind') == 'function' + renderer = (AutoFunctionRenderer if doclet.get('kind') in ['function', 'typedef'] else AutoAttributeRenderer) # Pass a dummy arg list with no formal param list so # _formal_params() won't find an explicit param list in there and diff --git a/tests/source/code.js b/tests/source/code.js index b482c3fc..8a5c48b7 100644 --- a/tests/source/code.js +++ b/tests/source/code.js @@ -90,3 +90,15 @@ const NoParamnames = {}; /** Thing to be shadowed in more_code.js */ function shadow() {} + +/** + * @typedef {Object} TypeDefinition + * @property {Number} width - width in pixels + */ + + +/** + * Some global callback + * @callback requestCallback + * @param {number} responseCode + */ diff --git a/tests/source/docs/autofunction_callback.rst b/tests/source/docs/autofunction_callback.rst new file mode 100644 index 00000000..ff2e0af1 --- /dev/null +++ b/tests/source/docs/autofunction_callback.rst @@ -0,0 +1 @@ +.. js:autofunction:: requestCallback diff --git a/tests/source/docs/autofunction_typedef.rst b/tests/source/docs/autofunction_typedef.rst new file mode 100644 index 00000000..389dbd55 --- /dev/null +++ b/tests/source/docs/autofunction_typedef.rst @@ -0,0 +1 @@ +.. js:autofunction:: TypeDefinition diff --git a/tests/test_build.py b/tests/test_build.py index c50fb8a0..4836bd67 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -58,6 +58,18 @@ def test_autofunction_long(self): 'autofunction_long', 'ContainingClass.someMethod(hi)\n\n Here.\n') + def test_autofunction_typedef(self): + """Make sure @typedef uses can be documented with autofunction.""" + self._file_contents_eq( + 'autofunction_typedef', + u'TypeDefinition()\n\n Arguments:\n * **width** (*Number*) – width in pixels\n') + + def test_autofunction_callback(self): + """Make sure @callback uses can be documented with autofunction.""" + self._file_contents_eq( + 'autofunction_callback', + u'requestCallback()\n\n Some global callback\n\n Arguments:\n * **responseCode** (*number*) –\n') + def test_autoclass(self): """Make sure classes show their class comment and constructor comment."""