Permalink
Browse files

Improved plugin api documentation

  • Loading branch information...
1 parent cd4727e commit a4e1fe47fd6266c358f1c25a03e9dcf3b926c4f5 @dbrgn dbrgn committed Dec 30, 2012
Showing with 79 additions and 62 deletions.
  1. +4 −4 docs/docs/plugin-api.rst
  2. +0 −2 docs/index.rst
  3. +7 −6 jedi/api.py
  4. +6 −5 jedi/api_classes.py
  5. +62 −45 jedi/settings.py
@@ -19,19 +19,19 @@ API Interface
~~~~~~~~~~~~~
.. automodule:: api
- :undoc-members:
API Return Classes
~~~~~~~~~~~~~~~~~~
.. automodule:: api_classes
- :undoc-members:
-Jedi setting interface
-~~~~~~~~~~~~~~~~~~~~~~
+Settings Module
+~~~~~~~~~~~~~~~
.. automodule:: settings
+ :no-members:
+ :no-undoc-members:
Examples
--------
View
@@ -6,8 +6,6 @@ Jedi
Release v\ |release|. (:doc:`Installation <docs/installation>`)
.. automodule:: jedi
- :members:
- :undoc-members:
Autocompletion can look like this (e.g. VIM plugin):
View
@@ -1,9 +1,10 @@
"""
-The api basically only provides one class. You can create a :class:`Script` and
-use it's ``complete`` / ``goto`` / etc functions.
+The API basically only provides one class. You can create a :class:`Script` and
+use its methods.
+
Additionally you can add a debug function with :func:`set_debug_function` and
-catch :exc:`NotFoundError` which is being raised if your completion is
-impossible.
+catch :exc:`NotFoundError` which is being raised if your completion is not
+possible.
"""
from __future__ import with_statement
__all__ = ['Script', 'NotFoundError', 'set_debug_function']
@@ -35,7 +36,7 @@ class NotFoundError(Exception):
class Script(object):
"""
A Script is the base for a completion, goto or whatever you want to do with
- jedi.
+ |jedi|.
:param source: The source code of the current file, separated by newlines.
:type source: string
@@ -71,7 +72,7 @@ def complete(self):
Return :class:`api_classes.Completion` objects. Those objects contain
information about the completions, more than just names.
- :return: completion objects, sorted by name and __ comes last.
+ :return: Completion objects, sorted by name and __ comes last.
:rtype: list of :class:`api_classes.Completion`
"""
def follow_imports_if_possible(name):
View
@@ -1,6 +1,7 @@
-"""`api_classes` contains the return classes of the API. These classes are the
-much bigger part of the whole API, because here you get out the information
-about completion and goto operations.
+"""
+The :mod:`api_classes` module contains the return classes of the API. These
+classes are the much bigger part of the whole API, because they contain the
+interesting information about completion and goto operations.
"""
import re
@@ -20,7 +21,7 @@
def _clear_caches():
"""
- Clears all caches of this and related modules. The only cache that will not
+ Clear all caches of this and related modules. The only cache that will not
be deleted is the module cache.
"""
cache.clear_caches()
@@ -231,7 +232,7 @@ def description(self):
def follow_definition(self):
"""
Return the original definitions. I strongly recommend not using it for
- your completions, because it might slow down *Jedi*. If you want to read
+ your completions, because it might slow down |jedi|. If you want to read
only a few objects (<=20), it might be useful, especially to
get the original docstrings. The basic problem of this function is
that it follows all results. This means with 1000 completions (e.g.
View
@@ -1,60 +1,77 @@
"""
-Variables to hold global jedi setting.
+This module contains variables with global |jedi| setting. To change the
+behavior of |jedi|, change the variables defined in
+:mod:`jedi.settings`.
-Plugin can change the variables defined in :mod:`jedi.settings` to
-modify behavior of Jedi. Plugin should expose an interface to setup
-these variables by user. Example usage::
+Plugins should expose an interface so that the user can adjust the
+configuration.
+
+
+Example usage::
from jedi import settings
settings.case_insensitive_completion = True
-* Completion output settings
- - :data:`case_insensitive_completion`
- - :data:`add_dot_after_module`
- - :data:`add_bracket_after_function`
- - :data:`no_completion_duplicates`
+Completion output
+~~~~~~~~~~~~~~~~~
+
+.. autodata:: case_insensitive_completion
+.. autodata:: add_dot_after_module
+.. autodata:: add_bracket_after_function
+.. autodata:: no_completion_duplicates
+
+
+Parser
+~~~~~~
+
+.. autodata:: fast_parser
+.. autodata:: fast_parser_always_reparse
+.. autodata:: use_get_in_function_call_cache
+
+
+Dynamic stuff
+~~~~~~~~~~~~~
+
+.. autodata:: dynamic_arrays_instances
+.. autodata:: dynamic_array_additions
+.. autodata:: dynamic_params
+.. autodata:: dynamic_params_for_other_modules
+.. autodata:: additional_dynamic_modules
-* Parser
- - :data:`fast_parser`
- - :data:`fast_parser_always_reparse`
- - :data:`use_get_in_function_call_cache`
+Recursions
+~~~~~~~~~~
-* Dynamic stuff
+Recursion settings are important if you don't want extremly
+recursive python code to go absolutely crazy. First of there is a
+global limit :data:`max_executions`. This limit is important, to set
+a maximum amount of time, the completion may use.
- - :data:`dynamic_arrays_instances`
- - :data:`dynamic_array_additions`
- - :data:`dynamic_params`
- - :data:`dynamic_params_for_other_modules`
- - :data:`additional_dynamic_modules`
+The default values are based on experiments while completing the |jedi| library
+itself (inception!). But I don't think there's any other Python library that
+uses recursion in a similarly extreme way. These settings make the completion
+definitely worse in some cases. But a completion should also be fast.
-* Recursions
+.. autodata:: max_until_execution_unique
+.. autodata:: max_function_recursion_level
+.. autodata:: max_executions_without_builtins
+.. autodata:: max_executions
+.. autodata:: scale_get_in_function_call
- Recursion settings are important if you don't want extremly
- recursive python code to go absolutely crazy. First of there is a
- global limit :data:`max_executions`. This limit is important, to set
- a maximum amount of time, the completion may use.
- The values are based on my experimental tries, used on the jedi library. But
- I don't think there's any other Python library, that uses recursion in a
- similar (extreme) way. This makes the completion definitely worse in some
- cases. But a completion should also be fast.
+Caching
+~~~~~~~
- - :data:`max_until_execution_unique`
- - :data:`max_function_recursion_level`
- - :data:`max_executions_without_builtins`
- - :data:`max_executions`
- - :data:`scale_get_in_function_call`
+.. autodata:: star_import_cache_validity
+.. autodata:: get_in_function_call_validity
-* Various
- - :data:`part_line_length`
+Various
+~~~~~~~
-* Caching validity (time)
+.. autodata:: part_line_length
- - :data:`star_import_cache_validity`
- - :data:`get_in_function_call_validity`
"""
@@ -116,7 +133,7 @@
dynamic_arrays_instances = True
"""
-check for `append`, etc. on array instances like list()
+Check for `append`, etc. on array instances like list()
"""
dynamic_array_additions = True
@@ -137,8 +154,8 @@
additional_dynamic_modules = []
"""
-Additional modules in which Jedi checks if statements are to be found. This
-is practical for IDE's, that want to administrate their modules themselves.
+Additional modules in which |jedi| checks if statements are to be found. This
+is practical for IDEs, that want to administrate their modules themselves.
"""
# ----------------
@@ -147,10 +164,10 @@
max_until_execution_unique = 50
"""
-The `max_until_execution_unique` limit is probably the most important one,
-because if that limit is passed, functions can only be one time executed. So
-new functions will be executed, complex recursions with the same functions
-again and again, are ignored.
+This limit is probably the most important one, because if this limit is
+exceeded, functions can only be one time executed. So new functions will be
+executed, complex recursions with the same functions again and again, are
+ignored.
"""
max_function_recursion_level = 5

0 comments on commit a4e1fe4

Please sign in to comment.