Skip to content
This repository has been archived by the owner on Jan 8, 2025. It is now read-only.

Commit

Permalink
Merge support for @callback and @typedef. Close #30.
Browse files Browse the repository at this point in the history
  • Loading branch information
erikrose committed Oct 10, 2017
2 parents d7460cf + 9fedbb1 commit 44d830d
Show file tree
Hide file tree
Showing 6 changed files with 41 additions and 9 deletions.
21 changes: 13 additions & 8 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <http://www.sphinx-doc.org/en/stable/tutorial.html#defining-document-structure>`_. 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 <http://www.sphinx-doc.org/en/stable/tutorial.html#defining-document-structure>`_. 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
Expand All @@ -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

Expand All @@ -118,6 +116,10 @@ extracted documentation::
.. js:autofunction:: someClass#someFunction
:short-name:

``autofunction`` can also be used on callbacks defined with the `@callback tag <http://usejsdoc.org/tags-callback.html>`_.

There is experimental support for abusing ``autofunction`` to document `@typedef tags <http://usejsdoc.org/tags-typedef.html>`_ 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
---------

Expand Down Expand Up @@ -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.
Expand Down
3 changes: 2 additions & 1 deletion sphinx_js/renderers.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down Expand Up @@ -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
Expand Down
12 changes: 12 additions & 0 deletions tests/source/code.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
1 change: 1 addition & 0 deletions tests/source/docs/autofunction_callback.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. js:autofunction:: requestCallback
1 change: 1 addition & 0 deletions tests/source/docs/autofunction_typedef.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.. js:autofunction:: TypeDefinition
12 changes: 12 additions & 0 deletions tests/test_build.py
Original file line number Diff line number Diff line change
Expand Up @@ -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."""
Expand Down

0 comments on commit 44d830d

Please sign in to comment.