[elpa] externals/javaimp 6ee0c1d726 2/3: Improve commentary

[Filipp Gunbin]

branch: externals/javaimp
commit 6ee0c1d726266b93d51c3a34014f3f605715b070
Author: Filipp Gunbin <fgunbin@fastmail.fm>
Commit: Filipp Gunbin <fgunbin@fastmail.fm>

    Improve commentary
---
 javaimp.el | 145 +++++++++++++++++++++++++++----------------------------------
 1 file changed, 63 insertions(+), 82 deletions(-)

diff --git a/javaimp.el b/javaimp.el
index ad7097e402..be1cba3b8a 100644
--- a/javaimp.el
+++ b/javaimp.el
@@ -22,19 +22,23 @@
 
 ;;; Commentary:
 
-;; Allows to manage Java import statements in Maven/Gradle projects.
-;; This module does not add all needed imports automatically!  It only
-;; helps you to quickly add imports when stepping through compilation
-;; errors.  In addition, this module provides good Imenu support for
-;; Java source files - with nesting and abstract methods in interfaces
-;; and abstract classes.  It provides suitable functions to use as
-;; `beginning-of-defun-function' / `end-of-defun-function' /
-;; `add-log-current-defun-function' as well.
+;; Allows to manage Java import statements in Maven / Gradle projects,
+;; plus some editing and navigation support.  This module does not add
+;; all needed imports automatically!  It only helps you to quickly add
+;; imports when stepping through compilation errors.  In addition,
+;; this module provides `javaimp-minor-mode' which enables decent
+;; Imenu support (with nesting and abstract methods in interfaces and
+;; abstract classes) and some navigation functions.
 ;;
+;;   Quick start
 ;;
-;;   Quick start:
+;; - Put something like this in your .emacs:
 ;;
-;; - Customize `javaimp-import-group-alist'.
+;; (require 'javaimp)
+;; (add-to-list 'javaimp-import-group-alist
+;;   '("\\`my.company\\." . 80))
+;; (keymap-global-set "C-c J v" #'javaimp-visit-project)
+;; (add-hook 'java-mode-hook #'javaimp-minor-mode)
 ;;
 ;; - Call `javaimp-visit-project', giving it the top-level build file
 ;; of your project.  If called within a project, supplies useful
@@ -46,29 +50,36 @@
 ;; `javaimp-add-import'.
 ;;
 ;;
-;;   Some details:
+;;   Visiting projects & managing imports
+;;
+;; Lists of classes in archive and source files, and Maven / Gradle
+;; project structures are cached, so usually only the first command
+;; should take a considerable amount of time to complete.  Project
+;; structure is re-read if a module's build file or any of its
+;; parents' build files (within visited tree) was modified since last
+;; check.
 ;;
-;; Contents of jar files, list of classes in source files, and
-;; Maven/Gradle project structures are cached, so usually only the
-;; first command should take a considerable amount of time to
-;; complete.  Project structure is re-read if a module's build file or
-;; any of its parents' build files (within visited tree) was modified
-;; since last check.  `javaimp-flush-cache' clears jar / source cache.
+;; `javaimp-flush-cache': command to clear jar / source cache.
 ;;
-;; To forget visited projects structure eval this:
-;; (setq javaimp-project forest nil)
+;; `javaimp-forget-visited-projects': command to forget all visited
+;; projects.
 ;;
 ;; Project structure and dependency information is retrieved from the
-;; build tool, see `javaimp-maven-visit' and `javaimp-gradle-visit',
-;; and the `javaimp-handler-regexp-alist' variable.  The output from
-;; the build tool can be inspected in buffer named by
-;; `javaimp-output-buf-name' variable.  If there exists
-;; Maven/Gradle wrapper in the project directory, as it is popular
-;; these days, it will be used in preference to `javaimp-mvn-program'
-;; / `javaimp-gradle-program'.
+;; corresponding build tool, see functions `javaimp-maven-visit' and
+;; `javaimp-gradle-visit' for details (and generally, all handlers
+;; mentioned in `javaimp-handler-regexp-alist').  The output from the
+;; build tool can be inspected in the buffer named by
+;; `javaimp-output-buf-name' variable.  If there exists Maven / Gradle
+;; wrapper in the project directory, as it is popular these days, it
+;; will be used in preference to `javaimp-mvn-program' /
+;; `javaimp-gradle-program'.
 ;;
-;; See docstring of `javaimp-add-import' for how import completion
-;; alternative are collected.
+;; `javaimp-java-home': defcustom giving location of JDK to use.
+;; Classes from JDK are included into import completion candidates.
+;; Also, when invoking a Java program, JAVA_HOME environment variable
+;; is added to the subprocess environment.  The variable is
+;; initialized from JAVA_HOME environment variable, so typically you
+;; won't need to customize it.
 ;;
 ;; If you get jar reading errors with Gradle despite following
 ;; recommendation which is shown (text from
@@ -77,67 +88,37 @@
 ;; those jars are really not built yet.  In this case, just build them
 ;; manually, like: './gradlew :project1:build :project2:build'.
 ;;
-;; Important defcustoms are:
-;;
-;; - `javaimp-java-home' - used to obtain classes in the JDK, and also
-;; the build tool is invoked with JAVA_HOME environment variable set
-;; to it.  It's initialized from JAVA_HOME env var, so typically it's
-;; not required to set it explicitly in Lisp.
-;;
-;; - `javaimp-parse-current-module' - determines whether we parse the
-;; current module for the list of classes.  Parsing is implemented in
-;; javaimp-parse.el using `syntax-ppss', generally is simple (we do
-;; not try to parse the source completely - just the interesting
-;; pieces), but can be time-consuming for large projects (to be
-;; improved).  Currently, on the author's machine, source for
-;; java.util.Collections from JDK 11 (~ 5600 lines and > 1000
-;; "scopes") parses in ~1.5 seconds, which is not that bad...
-;;
-;; Parsing is also used for Imenu support and for navigation commands.
-;; As there's no minor/major mode (yet), you have to set
-;; `imenu-create-index-function' and `beginning-of-defun-function' /
-;; `end-of-defun-function' / `add-log-current-defun-function' in major
-;; mode hook yourself.  See example below.
-;;
-;; - `javaimp-imenu-use-sub-alists' - if non-nil then Imenu items are
-;; presented in a nested fashion, instead of a flat list (the
-;; default).
-;;
-;; - `javaimp-verbose' - set to non-nil to get more messages about
-;; what Javaimp is doing.
-;;
-;; See other defcustoms via 'M-x customize-group javaimp'.
+;; `javaimp-add-import': command to add an import statement in the
+;; current file.  See its docstring for how completion candidates are
+;; collected.  When it is called for the first time in a given project
+;; / module, it parses dependency archives, as well as JDK ones, and
+;; it may take quite a while.
 ;;
+;; `javaimp-organize-import': command to organize imports in the
+;; current buffer, sorting and deleting duplicates.
 ;;
-;; `javaimp-show-scopes' lists all parsed "scopes" (blocks of code in
-;; braces), with support for `next-error'.
 ;;
+;;   Source parsing
 ;;
-;; Configuration example:
-;;
-;; (require 'javaimp)
-;; (add-to-list 'javaimp-import-group-alist
-;;   '("\\`\\(my\\.company\\.\\|my\\.company2\\.\\)" . 80))
-;; (global-set-key (kbd "C-c J v") 'javaimp-visit-project)
-;;
-;;
-;; And in `java-mode-hook':
-;;
-;; (local-set-key (kbd "C-c i") #'javaimp-add-import)
-;; (local-set-key (kbd "C-c o") #'javaimp-organize-imports)
-;; (local-set-key (kbd "C-c s") #'javaimp-show-scopes)
-;;
-;; To set imenu and navigation functions use:
+;; `javaimp-parse-current-module': defcustom which determines whether
+;; we parse the current module for the list of classes.  Parsing is
+;; implemented in javaimp-parse.el using `syntax-ppss', generally is
+;; simple (we do not try to parse the source completely - just the
+;; interesting pieces), but can be time-consuming for large projects
+;; (to be improved).  Currently, on the author's machine, source for
+;; java.util.Collections from JDK 11 (~ 5600 lines and > 1000
+;; "scopes") parses in ~1.5 seconds, which is not that bad...
 ;;
-;; (setq imenu-create-index-function #'javaimp-imenu-create-index)
+;; `javaimp-show-scopes': command to list all parsed "scopes" (blocks
+;; of code in braces) in the current buffer, with support for
+;; `next-error'.
 ;;
-;; (setq beginning-of-defun-function #'javaimp-beginning-of-defun)
-;; (setq end-of-defun-function #'javaimp-end-of-defun)
-;; (setq add-log-current-defun-function #'javaimp-add-log-current-defun)
-;; (define-key java-mode-map (kbd "C-M-a") #'beginning-of-defun)
-;; (define-key java-mode-map (kbd "C-M-e") #'end-of-defun)
+;; Parsing is also used for Imenu support and for navigation commands,
+;; these are installed by `javaimp-minor-mode'.
 ;;
-
+;; `javaimp-imenu-use-sub-alists': if non-nil then Imenu items are
+;; presented in a nested fashion, instead of a flat list (default is
+;; flat list).
 
 ;;; Code: