1 ;;; jde-javadoc-gen.el -- Javadoc builder
4 ;; Author: Sergey A Klibanov <sakliban@cs.wustl.edu>
5 ;; Maintainer: Paul Kinnucan, Sergey A Klibanov
6 ;; Keywords: java, tools
8 ;; Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 Paul Kinnucan.
10 ;; This file is not part of Emacs
12 ;; This program is free software; you can redistribute it and/or
13 ;; modify it under the terms of the GNU General Public License as
14 ;; published by the Free Software Foundation; either version 2, or (at
15 ;; your option) any later version.
17 ;; This program is distributed in the hope that it will be useful, but
18 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
19 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 ;; General Public License for more details.
22 ;; You should have received a copy of the GNU General Public License
23 ;; along with this program; see the file COPYING. If not, write to
24 ;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
25 ;; Boston, MA 02111-1307, USA.
35 (defgroup jde-javadoc nil
36 "Javadoc template generator"
38 :prefix "jde-javadoc-")
40 (defcustom jde-javadoc-display-doc t
41 "*Display the documentation generated by the `jde-javadoc-make' command. ."
45 (defcustom jde-javadoc-gen-detail-switch (list "-protected")
46 "Specifies what access level switch to use.
47 -public will show only public classes and members
48 -protected will show protected and public classes and members
49 -package will show package, protected, and public classes and members
50 -private will show all classes and members"
55 :tag "Select the detail level switch you want:"
61 (defcustom jde-javadoc-gen-packages nil
62 "Specifies which packages or files javadoc should be run on.
65 :type '(repeat (string :tag "Path")))
67 (defcustom jde-javadoc-gen-destination-directory "JavaDoc"
68 "Specifies the directory where javadoc will put the generated files.
69 The path may start with a tilde (~) or period (.) and may include
70 environment variables. The JDEE replaces a ~ with your home directory.
71 If `jde-resolve-relative-paths-p' is nonnil, the JDEE replaces the
72 . with the path of the current project file. The JDEE replaces each
73 instance of an environment variable with its value before inserting it
74 into the javadoc command line."
78 (defcustom jde-javadoc-gen-link-URL nil
79 "Specifies what URL's to link the generated files to.
80 For more information, look at the -link option of the javadoc tool."
82 :type '(repeat (string :tag "URL")))
84 (defcustom jde-javadoc-gen-link-online nil
85 "Specifies whether or not to use jde-javadoc-gen-link-URL."
89 (defcustom jde-javadoc-gen-link-offline nil
90 "Specifies URLs to link to and the local path to the directory holding the package-list for each URL.
91 The second argument can be a URL (http: or file:). If it is a relative file name, it is relative to the directory
92 from which javadoc is run."
95 (cons :tag "Remote URL and directory holding package-list for that URL"
97 (string :tag "Path"))))
99 (defcustom jde-javadoc-gen-group nil
100 "Specifies groups of packages with a group heading and package pattern.
101 The heading is usually a string like Extension Packages. The pattern is
102 any package name or wildcard matching that name. You can specify several
103 packages by separating the package names by a semicolon."
106 (cons :tag "Package group name and contents"
107 (string :tag "Heading")
108 (string :tag "Package Pattern"))))
110 (defcustom jde-javadoc-gen-doc-title ""
111 "Specifies the title to be placed near the top of the overview summary file."
115 (defcustom jde-javadoc-gen-window-title ""
116 "Specifies what should be placed in the HTML <title> tag.
117 Quotations inside the title should be escaped."
121 (defcustom jde-javadoc-gen-overview ""
122 "Specifies where to get an alternate overview-summary.html.
123 The path is relative to the sourcepath."
127 (defcustom jde-javadoc-gen-doclet ""
128 "Specifies the class file that starts an alternate doclet
129 to generate the html files. This path is relative to docletpath"
133 (defcustom jde-javadoc-gen-docletpath nil
134 "Specifies the path in which the doclet should be searched for."
136 :type '(repeat (string :tag "Path")))
138 (defcustom jde-javadoc-gen-header ""
139 "Specifies what html code should be placed at the top of each output file."
143 (defcustom jde-javadoc-gen-footer ""
144 "Specifies what html code should be placed at the bottom of each output file."
148 (defcustom jde-javadoc-gen-bottom ""
149 "Specifies what text or html code should be placed at the bottom
150 below the navigation bar."
154 (defcustom jde-javadoc-gen-helpfile ""
155 "Specifies the help file to be used for the Help link in the Navigation bar."
159 (defcustom jde-javadoc-gen-stylesheetfile ""
160 "Specifies the path to an alternate HTML stylesheet file."
164 (defcustom jde-javadoc-gen-split-index nil
165 "Specifies whether or not the index should be split alphabetically
166 one file per letter."
170 (defcustom jde-javadoc-gen-use nil
171 "Specifies whether or not to create \"Use\" pages"
175 (defcustom jde-javadoc-gen-author t
176 "Specifies whether or not to use @author tags"
180 (defcustom jde-javadoc-gen-version t
181 "Specifies whether or not to use @version tags"
185 (defcustom jde-javadoc-gen-serialwarn nil
186 "Specifies whether or not to generate compile-time errors for missed @serial tags"
190 (defcustom jde-javadoc-gen-nodeprecated nil
191 "Specifies whether or not to remove all references to deprecated code"
195 (defcustom jde-javadoc-gen-nodeprecatedlist nil
196 "Specifies whether or not to remove references to deprecated code
197 from the navigation bar, but not the rest of the documents."
201 (defcustom jde-javadoc-gen-notree nil
202 "Specifies whether or not to omit generating the class/interface hierarchy."
206 (defcustom jde-javadoc-gen-noindex nil
207 "Specifies whether or not to omit generating the index."
211 (defcustom jde-javadoc-gen-nohelp nil
212 "Specifies whether or not to omit the HELP link in the navigation bar of each page."
216 (defcustom jde-javadoc-gen-nonavbar nil
217 "Specifies whether or not to omit generating the navigation bar at the top of each page."
221 (defcustom jde-javadoc-gen-verbose nil
222 "Specifies whether or not javadoc should be verbose about what it is doing."
227 (defcustom jde-javadoc-gen-args nil
228 "Specifies any other arguments that you want to pass to javadoc."
230 :type '(repeat (string :tag "Argument")))
232 (defclass jde-javadoc-maker (efc-compiler)
233 ((make-packages-p :initarg :make-packages-p
236 :documentation "Nonnil generates doc for packages."))
237 "Class of Javadoc generators.")
239 (defmethod initialize-instance ((this jde-javadoc-maker) &rest fields)
240 "Initialize the Javadoc generator."
242 (oset this name "javadoc")
250 jde-javadoc-display-doc
251 (string-match "finished" msg))
256 jde-javadoc-gen-destination-directory
257 'jde-javadoc-gen-destination-directory))))))
262 (jde-cygpath (expand-file-name "bin/javadoc" (jde-get-jdk-dir)) t)))
264 (defmethod get-args ((this jde-javadoc-maker))
265 "Get the arguments to pass to the javadoc process as specified
266 by the jde-javadoc-gen variables."
267 (let* ((destination-directory
269 jde-javadoc-gen-destination-directory
270 'jde-javadoc-gen-destination-directory))
273 "-d" destination-directory
274 (car jde-javadoc-gen-detail-switch))))
276 (if (not (file-exists-p destination-directory))
277 (make-directory destination-directory))
279 ;;Insert online links
280 (if jde-javadoc-gen-link-online
285 (lambda (link) (list "-link" link))
286 jde-javadoc-gen-link-URL))))
288 ;;Insert offline links
289 (if jde-javadoc-gen-link-offline
295 (list "-linkoffline" (car link) (cdr link)))
296 jde-javadoc-gen-link-offline))))
299 (if jde-javadoc-gen-group
305 (list "-group" (car group) (cdr group)))
306 jde-javadoc-gen-group))))
310 (if jde-global-classpath
317 (jde-get-global-classpath)
318 'jde-global-classpath)))))
333 ;; Insert bootclasspath
334 (if jde-compile-option-bootclasspath
341 jde-compile-option-bootclasspath
342 'jde-compile-option-bootclasspath)))))
345 (if jde-compile-option-extdirs
352 jde-compile-option-extdirs
353 'jde-compile-option-extdirs)))))
355 ;; Insert windowtitle
356 (if (not (equal "" jde-javadoc-gen-window-title))
362 jde-javadoc-gen-window-title))))
365 (if (not (equal "" jde-javadoc-gen-doc-title))
371 jde-javadoc-gen-doc-title))))
374 (if (not (equal "" jde-javadoc-gen-header))
380 jde-javadoc-gen-header))))
383 (if (not (equal "" jde-javadoc-gen-footer))
389 jde-javadoc-gen-footer))))
392 (if (not (equal "" jde-javadoc-gen-bottom))
398 jde-javadoc-gen-bottom))))
401 (if (not (equal "" jde-javadoc-gen-helpfile))
407 (jde-normalize-path 'jde-javadoc-gen-helpfile)))))
410 (if (not (equal "" jde-javadoc-gen-stylesheetfile))
416 (jde-normalize-path 'jde-javadoc-gen-stylesheetfile)))))
419 (if (not (equal "" jde-javadoc-gen-overview))
425 jde-javadoc-gen-overview))))
428 (if (not (equal "" jde-javadoc-gen-doclet))
434 jde-javadoc-gen-doclet))))
436 ;; Insert -docletpath
437 (if jde-javadoc-gen-docletpath
444 jde-javadoc-gen-docletpath
445 'jde-javadoc-gen-docletpath)))))
448 (if jde-javadoc-gen-use
455 (if jde-javadoc-gen-author
462 (if jde-javadoc-gen-version
469 (if jde-javadoc-gen-split-index
473 (list "-splitindex"))))
475 ;;Insert -nodeprecated
476 (if jde-javadoc-gen-nodeprecated
480 (list "-nodeprecated"))))
482 ;;Insert -nodeprecatedlist
483 (if jde-javadoc-gen-nodeprecatedlist
487 (list "-nodeprecatedlist"))))
490 (if jde-javadoc-gen-notree
497 (if jde-javadoc-gen-noindex
504 (if jde-javadoc-gen-nohelp
511 (if jde-javadoc-gen-nonavbar
515 (list "-nonavbar"))))
518 (if jde-javadoc-gen-serialwarn
522 (list "-serialwarn"))))
525 (if jde-javadoc-gen-verbose
532 (if jde-javadoc-gen-args
536 jde-javadoc-gen-args)))
538 ;;Insert packages/files
539 (if (and (oref this make-packages-p) jde-javadoc-gen-packages)
544 (lambda (packagename) packagename)
545 jde-javadoc-gen-packages)))
548 (append args (list (buffer-file-name)))))))
552 (defun jde-javadoc-make-internal (&optional make-packages-p)
553 "Generates javadoc for the current project if MAKE-PACKAGES-P
554 and `jde-javadoc-gen-packages' are nonnil; otherwise, make doc
555 for the current buffer. This command runs the
556 currently selected javadoc's program to generate the documentation.
557 It uses `jde-get-jdk-dir' to determine the location of
558 the currentlyh selected JDK. The variable `jde-global-classpath' specifies
559 the javadoc -classpath argument. The variable `jde-sourcepath'
560 specifies the javadoc -sourcepath argument. You can specify all
561 other javadoc options via JDE customization variables. To specify the
562 options, select Project->Options->Javadoc from the JDE menu. Use
563 `jde-javadoc-gen-packages' to specify the packages, classes, or source
564 files for which you want to generate javadoc. If this variable is nil,
565 this command generates javadoc for the Java source file in the current
566 buffer. If `jde-javadoc-display-doc' is nonnil, this command displays
567 the generated documentation in a browser."
572 :make-packages-p make-packages-p)))
578 (defun jde-javadoc-make ()
579 "Generates javadoc for the current project. This command runs the
580 currently selected JDK's javadoc program to generate the documentation.
581 It uses `jde-get-jdk-dir' to determine the location of the currently
582 selected JDK. The variable `jde-global-classpath' specifies the javadoc
583 -classpath argument. The variable `jde-sourcepath'
584 specifies the javadoc -sourcepath argument. You can specify all
585 other javadoc options via JDE customization variables. To specify the
586 options, select Project->Options->Javadoc from the JDE menu. Use
587 `jde-javadoc-gen-packages' to specify the packages, classes, or source
588 files for which you want to generate javadoc. If this variable is nil,
589 this command generates javadoc for the Java source file in the current
590 buffer. If `jde-javadoc-display-doc' is nonnil, this command displays
591 the generated documentation in a browser."
593 (jde-javadoc-make-internal t))
596 (defun jde-javadoc-make-buffer ()
597 "Generates javadoc for the current buffer. This command runs the
598 currently selected JDK's javadoc program to generate the
599 documentation. It uses `jde-get-jdk-dir' to determine the location of the currently
600 selected JDK. The variable `jde-global-classpath' specifies the
601 javadoc -classpath argument. The variable `jde-sourcepath' specifies
602 the javadoc -sourcepath argument. You can specify all other javadoc
603 options via JDE customization variables. To specify the options,
604 select Project->Options->Javadoc from the JDE menu. Use
605 `jde-javadoc-make' to generate doc for the files and packages
606 specified by `jde-javadoc-gen-packages'. If `jde-javadoc-display-doc'
607 is nonnil, this command displays the generated documentation in a
610 (jde-javadoc-make-internal))
612 (defun jde-javadoc-browse-tool-doc ()
613 "Displays the documentation for the javadoc tool in a browser."
615 (let* ((jdk-url (jde-help-get-jdk-doc-url))
618 (substring jdk-url 0 (string-match "index" jdk-url))
619 (if (eq system-type 'windows-nt) "tooldocs/windows/" "tooldocs/solaris/")
624 'browse-url-new-window-flag)
625 browse-url-new-window-flag
626 browse-url-new-window-p))))
629 (provide 'jde-javadoc-gen)
632 ;; $Log: jde-javadoc-gen.el,v $
633 ;; Revision 1.18 2005/01/10 05:38:53 paulk
634 ;; Remove quoting from string arguments passed to javadoc command. This is unnecessary as w32-quote-args is set to nonnil, i.e., Emacs puts quotes around strings that it passes to javadoc.
636 ;; Revision 1.17 2004/03/21 02:53:53 paulk
637 ;; Fixed incorrect handling of jde-javadoc-gen-args option that caused a Lisp error.
639 ;; Revision 1.16 2003/08/28 05:15:15 paulk
640 ;; Now launches javadoc directly instead of via the current shell. This avoids the need
641 ;; to quote command-line arguments, which always causes problems.
643 ;; Revision 1.15 2003/06/20 03:12:02 paulk
644 ;; Update docstrings.
646 ;; Revision 1.14 2003/06/17 05:54:09 paulk
647 ;; - Now uses jde-get-jdk-dir to determine the location of the javadoc
650 ;; - Adds a jde-javadoc-make-buffer command to generate doc only for the
651 ;; source file in the current buffer.
653 ;; Revision 1.13 2003/06/05 03:58:38 paulk
654 ;; Add more precise check for existence of destination directory. Add
655 ;; call to jde-update-autoloaded-symbols to ensure that the autoloade
656 ;; customization variables defined by this package are initialized to the
657 ;; values defined by the current project.
659 ;; Revision 1.12 2002/12/30 05:01:45 paulk
660 ;; Fixed regression in jde-javadoc-make command.
662 ;; Revision 1.11 2002/12/21 08:59:39 paulk
663 ;; Fix docstring for jde-javadoc-gen-destination-directory.
665 ;; Revision 1.10 2002/12/21 08:45:43 paulk
666 ;; Normalize jde-javadoc-gen-destination-directory.
668 ;; Revision 1.9 2002/06/12 07:04:25 paulk
669 ;; XEmacs compatibility fix: set win32-quote-process-args wherever
670 ;; the JDEE sets w32-quote-process-args. This allows use of spaces in
671 ;; paths passed as arguments to processes (e.g., javac) started by
674 ;; Revision 1.8 2002/06/11 06:44:05 paulk
675 ;; Provides support for paths containing spaces as javadoc arguments via the following change:
676 ;; locally set the w32-quote-process-args variable to a quotation mark when launching
677 ;; the javadoc process.
679 ;; Revision 1.7 2002/03/31 07:49:50 paulk
680 ;; Renamed jde-db-source-directories. The new name is jde-sourcepath.
682 ;; Revision 1.6 2001/04/16 05:56:42 paulk
683 ;; Normalize paths. Thanks to Nick Sieger.
685 ;; Revision 1.5 2001/04/11 03:19:43 paulk
686 ;; Updated to resolve relative paths relative to the project file that defines them. Thanks to Nick Sieger.
688 ;; Revision 1.4 2001/03/22 18:51:33 paulk
689 ;; Quote buffer path argument on command line to accommodate paths with spaces in them as permitted on Windows. Thanks to "Jeffrey Phillips" <jeffrey.phillips@staffeon.com> for reporting this problem and providing a fix.
691 ;; Revision 1.3 2001/03/01 04:23:28 paulk
692 ;; Fixed incorrect generation of javadoc index path in jde-javadoc-make function. "William G. Griswold" <wgg@cs.ucsd.edu> for this fix.
694 ;; Revision 1.2 2001/01/27 05:53:38 paulk
695 ;; No longer inserts -sourcepath argument twice in the javadoc command line.
697 ;; Revision 1.1 2000/10/20 04:06:34 paulk
702 ;;; jde-javadoc-gen.el ends here