Initial Commit
[packages] / xemacs-packages / jde / lisp / jde-javadoc-gen.el
1 ;;; jde-javadoc-gen.el -- Javadoc builder
2 ;; $Revision: 1.18 $ 
3
4 ;; Author: Sergey A Klibanov <sakliban@cs.wustl.edu>
5 ;; Maintainer: Paul Kinnucan, Sergey A Klibanov
6 ;; Keywords: java, tools
7
8 ;; Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005 Paul Kinnucan.
9
10 ;; This file is not part of Emacs
11
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.
16
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.
21
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.
26
27 ;;; Commentary:
28
29 ;;; Code:
30
31 ;;;;
32 ;;;; Customization
33 ;;;;
34
35 (defgroup jde-javadoc nil
36   "Javadoc template generator"
37   :group 'jde
38   :prefix "jde-javadoc-")
39
40 (defcustom jde-javadoc-display-doc t
41   "*Display the documentation generated by the `jde-javadoc-make' command. ."
42   :group 'jde-javadoc
43   :type 'boolean)
44
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"
51   :group 'jde-javadoc
52   :type '(list
53           (radio-button-choice
54            :format "%t \n%v"
55            :tag "Select the detail level switch you want:"
56            (const "-public")
57            (const "-protected")
58            (const "-package")
59            (const "-private"))))
60
61 (defcustom jde-javadoc-gen-packages nil
62   "Specifies which packages or files javadoc should be run on.
63 "
64   :group 'jde-javadoc
65   :type '(repeat (string :tag "Path")))
66
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."
75   :group 'jde-javadoc
76   :type 'string)
77
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."
81   :group 'jde-javadoc
82   :type '(repeat (string :tag "URL")))
83
84 (defcustom jde-javadoc-gen-link-online nil
85   "Specifies whether or not to use jde-javadoc-gen-link-URL."
86   :group 'jde-javadoc
87   :type 'boolean)
88
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."
93   :group 'jde-javadoc
94   :type '(repeat 
95           (cons :tag "Remote URL and directory holding package-list for that URL"
96                 (string :tag "URL")
97                 (string :tag "Path"))))
98
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."
104   :group 'jde-javadoc
105   :type '(repeat
106           (cons :tag "Package group name and contents"
107                 (string :tag "Heading")
108                 (string :tag "Package Pattern"))))
109
110 (defcustom jde-javadoc-gen-doc-title ""
111   "Specifies the title to be placed near the top of the overview summary file."
112   :group 'jde-javadoc
113   :type 'string)
114
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."
118   :group 'jde-javadoc
119   :type 'string)
120
121 (defcustom jde-javadoc-gen-overview ""
122   "Specifies where to get an alternate overview-summary.html.
123    The path is relative to the sourcepath."
124   :group 'jde-javadoc
125   :type 'string)
126
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"
130   :group 'jde-javadoc
131   :type 'string)
132
133 (defcustom jde-javadoc-gen-docletpath nil
134   "Specifies the path in which the doclet should be searched for."
135   :group 'jde-javadoc
136   :type '(repeat (string :tag "Path")))
137
138 (defcustom jde-javadoc-gen-header ""
139   "Specifies what html code should be placed at the top of each output file."
140   :group 'jde-javadoc
141   :type 'string)
142
143 (defcustom jde-javadoc-gen-footer ""
144   "Specifies what html code should be placed at the bottom of each output file."
145   :group 'jde-javadoc
146   :type 'string)
147
148 (defcustom jde-javadoc-gen-bottom ""
149   "Specifies what text or html code should be placed at the bottom
150    below the navigation bar."
151   :group 'jde-javadoc
152   :type 'string)
153
154 (defcustom jde-javadoc-gen-helpfile ""
155   "Specifies the help file to be used for the Help link in the Navigation bar."
156   :group 'jde-javadoc
157   :type 'string)
158
159 (defcustom jde-javadoc-gen-stylesheetfile ""
160   "Specifies the path to an alternate HTML stylesheet file."
161   :group 'jde-javadoc
162   :type 'string)
163
164 (defcustom jde-javadoc-gen-split-index nil
165   "Specifies whether or not the index should be split alphabetically
166    one file per letter."
167   :group 'jde-javadoc
168   :type 'boolean)
169
170 (defcustom jde-javadoc-gen-use nil
171   "Specifies whether or not to create \"Use\" pages"
172   :group 'jde-javadoc
173   :type 'boolean)
174
175 (defcustom jde-javadoc-gen-author t
176   "Specifies whether or not to use @author tags"
177   :group 'jde-javadoc
178   :type 'boolean)
179
180 (defcustom jde-javadoc-gen-version t
181   "Specifies whether or not to use @version tags"
182   :group 'jde-javadoc
183   :type 'boolean)
184
185 (defcustom jde-javadoc-gen-serialwarn nil
186   "Specifies whether or not to generate compile-time errors for missed @serial tags"
187   :group 'jde-javadoc
188   :type 'boolean)
189
190 (defcustom jde-javadoc-gen-nodeprecated nil
191   "Specifies whether or not to remove all references to deprecated code"
192   :group 'jde-javadoc
193   :type 'boolean)
194
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."
198   :group 'jde-javadoc
199   :type 'boolean)
200
201 (defcustom jde-javadoc-gen-notree nil
202   "Specifies whether or not to omit generating the class/interface hierarchy."
203   :group 'jde-javadoc
204   :type 'boolean)
205
206 (defcustom jde-javadoc-gen-noindex nil
207   "Specifies whether or not to omit generating the index."
208   :group 'jde-javadoc
209   :type 'boolean)
210
211 (defcustom jde-javadoc-gen-nohelp nil
212   "Specifies whether or not to omit the HELP link in the navigation bar of each page."
213   :group 'jde-javadoc
214   :type 'boolean)
215
216 (defcustom jde-javadoc-gen-nonavbar nil
217   "Specifies whether or not to omit generating the navigation bar at the top of each page."
218   :group 'jde-javadoc
219   :type 'boolean)
220
221 (defcustom jde-javadoc-gen-verbose nil
222   "Specifies whether or not javadoc should be verbose about what it is doing."
223   :group 'jde-javadoc
224   :type 'boolean)
225
226
227 (defcustom jde-javadoc-gen-args nil
228   "Specifies any other arguments that you want to pass to javadoc."
229   :group 'jde-javadoc
230   :type '(repeat (string :tag "Argument")))
231
232 (defclass jde-javadoc-maker (efc-compiler) 
233   ((make-packages-p  :initarg :make-packages-p
234                      :type boolean
235                      :initform t
236                      :documentation "Nonnil generates doc for packages."))
237   "Class of Javadoc generators.")
238
239 (defmethod initialize-instance ((this jde-javadoc-maker) &rest fields)
240   "Initialize the Javadoc generator."
241
242   (oset this name "javadoc")
243
244   (oset 
245    this 
246    comp-finish-fcn
247    (lambda (buf msg)
248      (message msg)
249      (if (and
250           jde-javadoc-display-doc
251           (string-match "finished" msg))
252          (browse-url-of-file 
253           (expand-file-name  
254            "index.html" 
255            (jde-normalize-path 
256             jde-javadoc-gen-destination-directory 
257             'jde-javadoc-gen-destination-directory))))))
258
259   (oset 
260    this 
261    exec-path 
262    (jde-cygpath (expand-file-name "bin/javadoc" (jde-get-jdk-dir)) t)))
263
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
268           (jde-normalize-path 
269            jde-javadoc-gen-destination-directory 
270            'jde-javadoc-gen-destination-directory))
271          (args 
272           (list
273            "-d" destination-directory
274            (car jde-javadoc-gen-detail-switch))))
275
276     (if (not (file-exists-p destination-directory)) 
277         (make-directory destination-directory))
278
279     ;;Insert online links
280     (if jde-javadoc-gen-link-online 
281         (setq args 
282               (append
283                args
284                (mapcan
285                 (lambda (link)  (list "-link" link))
286                 jde-javadoc-gen-link-URL))))
287     
288     ;;Insert offline links
289     (if jde-javadoc-gen-link-offline
290         (setq args
291               (append 
292                args
293                (mapcan
294                 (lambda (link) 
295                   (list "-linkoffline" (car  link) (cdr link)))
296                 jde-javadoc-gen-link-offline))))
297
298     ;;Insert -group
299     (if jde-javadoc-gen-group
300         (setq args
301               (append
302                args
303                (mapcan
304                 (lambda (group) 
305                   (list "-group" (car group) (cdr group)))
306                 jde-javadoc-gen-group))))
307
308
309      ;; Insert classpath
310     (if jde-global-classpath
311         (setq args
312               (append
313                args
314                (list
315                 "-classpath"
316                 (jde-build-classpath
317                  (jde-get-global-classpath)
318                  'jde-global-classpath)))))
319
320
321     ;; Insert sourcepath
322     (if jde-sourcepath
323         (setq args
324               (append
325                args
326                (list
327                 "-sourcepath"
328                 (jde-build-classpath
329                  jde-sourcepath
330                  'jde-sourcepath)))))
331
332
333     ;; Insert bootclasspath
334     (if jde-compile-option-bootclasspath
335         (setq args
336               (append
337                args
338                (list
339                 "-bootclasspath"
340                (jde-build-classpath
341                 jde-compile-option-bootclasspath
342                 'jde-compile-option-bootclasspath)))))
343
344     ;; Insert extdirs
345     (if jde-compile-option-extdirs
346         (setq args
347               (append
348                args
349                (list
350                 "-extdirs"
351                (jde-build-classpath
352                 jde-compile-option-extdirs
353                 'jde-compile-option-extdirs)))))
354
355     ;; Insert windowtitle
356     (if (not (equal "" jde-javadoc-gen-window-title))
357         (setq args
358               (append
359                args 
360                (list
361                 "-windowtitle"
362                 jde-javadoc-gen-window-title))))
363
364     ;; Insert doctitle
365     (if (not (equal "" jde-javadoc-gen-doc-title))
366         (setq args
367               (append
368                args 
369                (list
370                 "-doctitle"
371                 jde-javadoc-gen-doc-title))))
372
373     ;; Insert header
374     (if (not (equal "" jde-javadoc-gen-header))
375         (setq args
376               (append
377                args 
378                (list
379                 "-header"
380                 jde-javadoc-gen-header))))
381
382     ;; Insert footer
383     (if (not (equal "" jde-javadoc-gen-footer))
384         (setq args
385               (append
386                args 
387                (list 
388                 "-footer"
389                 jde-javadoc-gen-footer))))
390
391     ;; Insert bottom
392     (if (not (equal "" jde-javadoc-gen-bottom))
393         (setq args
394               (append
395                args
396                (list 
397                 "-bottom"
398                 jde-javadoc-gen-bottom))))
399
400     ;; Insert helpfile
401     (if (not (equal "" jde-javadoc-gen-helpfile))
402         (setq args
403               (append
404                args 
405                (list
406                "-helpfile"
407                (jde-normalize-path 'jde-javadoc-gen-helpfile)))))
408
409     ;; Insert stylesheet
410     (if (not (equal "" jde-javadoc-gen-stylesheetfile))
411         (setq args
412               (append
413                args 
414                (list 
415                 "-stylesheetfile"
416                 (jde-normalize-path 'jde-javadoc-gen-stylesheetfile)))))
417
418     ;; Insert -overview
419     (if (not (equal "" jde-javadoc-gen-overview))
420         (setq args
421               (append
422                args 
423                (list 
424                 "-overview"
425                 jde-javadoc-gen-overview))))
426
427     ;; Insert -doclet
428     (if (not (equal "" jde-javadoc-gen-doclet))
429         (setq args
430               (append
431                args 
432                (list
433                 "-doclet"
434                 jde-javadoc-gen-doclet))))
435
436     ;; Insert -docletpath
437     (if jde-javadoc-gen-docletpath
438         (setq args
439               (append
440                args
441                (list
442                 "-docletpath"
443                (jde-build-classpath
444                 jde-javadoc-gen-docletpath
445                 'jde-javadoc-gen-docletpath)))))
446
447     ;; Inser -use
448     (if jde-javadoc-gen-use
449         (setq args
450               (append
451                args 
452                (list "-use"))))
453
454     ;;Insert -author
455     (if jde-javadoc-gen-author
456         (setq args
457               (append
458                args 
459                (list "-author"))))
460     
461     ;;Insert -version
462     (if jde-javadoc-gen-version
463         (setq args
464               (append
465                args 
466                (list "-version"))))
467
468     ;;Insert -splitindex
469     (if jde-javadoc-gen-split-index
470         (setq args
471               (append
472                args 
473                (list "-splitindex"))))
474
475     ;;Insert -nodeprecated
476     (if jde-javadoc-gen-nodeprecated
477         (setq args
478               (append 
479                args 
480                (list "-nodeprecated"))))
481
482     ;;Insert -nodeprecatedlist
483     (if jde-javadoc-gen-nodeprecatedlist
484         (setq args
485               (append 
486                args 
487                (list "-nodeprecatedlist"))))
488
489     ;;Insert -notree
490     (if jde-javadoc-gen-notree
491         (setq args
492               (append
493                args 
494                (list "-notree"))))
495
496     ;;Insert -noindex
497     (if jde-javadoc-gen-noindex
498         (setq args
499               (append
500                args 
501                (list "-noindex"))))
502
503     ;;Insert -nohelp
504     (if jde-javadoc-gen-nohelp
505         (setq args
506               (append
507                args 
508                (list "-nohelp"))))
509
510     ;;Insert -nonavbar
511     (if jde-javadoc-gen-nonavbar
512         (setq args
513               (append
514                args 
515                (list "-nonavbar"))))
516
517     ;;Insert -serialwarn
518     (if jde-javadoc-gen-serialwarn
519         (setq args
520               (append
521                args 
522                (list  "-serialwarn"))))
523
524     ;;Insert -verbose
525     (if jde-javadoc-gen-verbose
526         (setq args
527               (append
528                args 
529                (list  "-verbose"))))
530
531     ;;Insert other tags
532     (if jde-javadoc-gen-args
533         (setq args
534               (append
535                args
536                jde-javadoc-gen-args)))
537
538     ;;Insert packages/files
539     (if (and (oref this make-packages-p) jde-javadoc-gen-packages)
540         (setq args 
541               (append 
542                args
543                (mapcar
544                 (lambda (packagename) packagename)
545                 jde-javadoc-gen-packages)))
546       (setq 
547        args
548        (append args (list (buffer-file-name)))))))
549          
550
551 ;;;###autoload
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."
568   (save-some-buffers)
569   (let ((generator 
570          (jde-javadoc-maker
571           "javadoc generator"
572           :make-packages-p make-packages-p)))
573     (exec generator)))
574
575
576
577 ;;;###autoload
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."
592   (interactive)
593   (jde-javadoc-make-internal t))
594
595 ;;;###autoload
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
608 browser."
609   (interactive)
610   (jde-javadoc-make-internal))
611
612 (defun jde-javadoc-browse-tool-doc ()
613   "Displays the documentation for the javadoc tool in a browser."
614   (interactive)
615   (let* ((jdk-url (jde-help-get-jdk-doc-url))
616          (javadoc-url
617           (concat
618            (substring jdk-url 0 (string-match "index" jdk-url))
619            (if (eq system-type 'windows-nt) "tooldocs/windows/" "tooldocs/solaris/")
620            "javadoc.html")))
621     (browse-url 
622      javadoc-url
623      (if (boundp 
624           'browse-url-new-window-flag)
625          browse-url-new-window-flag
626        browse-url-new-window-p))))
627
628
629 (provide 'jde-javadoc-gen)
630
631 ;;
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.
635 ;;
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.
638 ;;
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.
642 ;;
643 ;; Revision 1.15  2003/06/20 03:12:02  paulk
644 ;; Update docstrings.
645 ;;
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
648 ;;   executable.
649 ;;
650 ;; - Adds a jde-javadoc-make-buffer command to generate doc only for the
651 ;;   source file in the current buffer.
652 ;;
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.
658 ;;
659 ;; Revision 1.12  2002/12/30 05:01:45  paulk
660 ;; Fixed regression in jde-javadoc-make command.
661 ;;
662 ;; Revision 1.11  2002/12/21 08:59:39  paulk
663 ;; Fix docstring for jde-javadoc-gen-destination-directory.
664 ;;
665 ;; Revision 1.10  2002/12/21 08:45:43  paulk
666 ;; Normalize jde-javadoc-gen-destination-directory.
667 ;;
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
672 ;; the JDEE.
673 ;;
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.
678 ;;
679 ;; Revision 1.7  2002/03/31 07:49:50  paulk
680 ;; Renamed jde-db-source-directories. The new name is jde-sourcepath.
681 ;;
682 ;; Revision 1.6  2001/04/16 05:56:42  paulk
683 ;; Normalize paths. Thanks to Nick Sieger.
684 ;;
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.
687 ;;
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.
690 ;;
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.
693 ;;
694 ;; Revision 1.2  2001/01/27 05:53:38  paulk
695 ;; No longer inserts -sourcepath argument twice in the javadoc command line.
696 ;;
697 ;; Revision 1.1  2000/10/20 04:06:34  paulk
698 ;; Initial version.
699 ;;
700 ;;
701
702 ;;; jde-javadoc-gen.el ends here