From 9fedbb17151594c31dd86cc49340a5fd47ee0f2b Mon Sep 17 00:00:00 2001 From: Erik Rose Date: Tue, 10 Oct 2017 15:38:04 -0400 Subject: [PATCH] Document callback and typedef support for autofunction. Also improve flow of readme for first-timers. --- README.rst | 20 +++++++++++++------- tests/test_build.py | 4 ++-- 2 files changed, 15 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index 9c95a723..884c04b0 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,6 +261,10 @@ Run ``python setup.py test``. Run ``tox`` to test across Python versions. Version History =============== +2.2 + * Add ``autofunction`` support for ``@callback`` tags. + * Add experimental ``autofunction`` support for ``@typedef`` tags. + 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. * Aggregate PathTaken errors, and report them all at once. This means you don't have to run JSDoc repeatedly while cleaning up large projects. diff --git a/tests/test_build.py b/tests/test_build.py index c7df2b0d..4836bd67 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -59,13 +59,13 @@ def test_autofunction_long(self): 'ContainingClass.someMethod(hi)\n\n Here.\n') def test_autofunction_typedef(self): - """Make that typedef works.""" + """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 that callback works.""" + """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')