forked from emacsattic/doxymacs
/
doxymacs.el.in
1865 lines (1712 loc) · 67.3 KB
/
doxymacs.el.in
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
;;; -*-emacs-lisp-*-
;;; doxymacs.el --- ELisp package for making doxygen related stuff easier.
;;
;;
;; Copyright (C) 2001-2010 Ryan T. Sammartino
;;
;; Author: Ryan T. Sammartino <ryan.sammartino at gmail dot com>
;; Kris Verbeeck <kris.verbeeck at advalvas dot be>
;; Created: 24/03/2001
;; Version: @VERSION@
;; Keywords: doxygen documentation
;;
;; This file is NOT part of GNU Emacs or XEmacs.
;;
;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License
;; as published by the Free Software Foundation; either version 2
;; of the License, or (at your option) any later version.
;;
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with this program; if not, write to the Free Software
;; Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
;;
;; Doxymacs homepage: http://doxymacs.sourceforge.net/
;; Commentary:
;;
;; Doxymacs depends on the following packages:
;;
;; - W3 http://www.cs.indiana.edu/usr/local/www/elisp/w3/docs.html
;; - tempo http://www.lysator.liu.se/~davidk/elisp/
;; - libxml2 http://www.libxml.org/
;;
;; Be sure these are properly configured and installed before proceeding.
;;
;; - Use the configure script to configure doxymacs:
;;
;; $ ./configure
;; $ make
;; $ make install
;;
;; Use ./configure --help for help on customising your configuration.
;;
;; If you get
;;
;; !! File error (("Cannot open load file" "url"))
;;
;; (or something similar) then set the variable EMACSLOADPATH before
;; doing make:
;;
;; $ EMACSLOADPATH=... make
;;
;; where ... is a colon separated list of directories to search for
;; packages. To byte compile with XEmacs, set the variable EMACS:
;;
;; $ EMACS=xemacs make
;;
;; If you would rather not byte compile the .el files at all, then do:
;;
;; $ make ELCFILES=
;;
;; - Customise the variable doxymacs-doxygen-dirs.
;;
;; - If your tags file is quite large (say, > 1 MB), consider setting
;; doxymacs-use-external-xml-parser to t and be sure to set
;; doxymacs-external-xml-parser-executable to the right value (the
;; default should usually be fine). A suitable program is
;; distributed along with this file in the directory doxymacs/c/.
;; With an 11 MB XML tag file, the internal process takes 20 minutes
;; on a PIII 800 with 1 GB of RAM, whereas the external process
;; takes 12 seconds.
;;
;; - Put (require 'doxymacs) in your .emacs
;;
;; - Invoke doxymacs-mode with M-x doxymacs-mode. To have doxymacs-mode
;; invoked automatically when in C/C++ mode, put
;;
;; (add-hook 'c-mode-common-hook 'doxymacs-mode)
;;
;; in your .emacs.
;;
;; - If you want Doxygen keywords fontified use M-x doxymacs-font-lock.
;; To do it automatically, add the following to your .emacs:
;;
;; (defun my-doxymacs-font-lock-hook ()
;; (if (or (eq major-mode 'c-mode) (eq major-mode 'c++-mode))
;; (doxymacs-font-lock)))
;; (add-hook 'font-lock-mode-hook 'my-doxymacs-font-lock-hook)
;;
;; This will add the Doxygen keywords to c-mode and c++-mode only.
;;
;; - Default key bindings are:
;; - C-c d ? will look up documentation for the symbol under the point.
;; - C-c d r will rescan your Doxygen tags file.
;; - C-c d f will insert a Doxygen comment for the next function.
;; - C-c d i will insert a Doxygen comment for the current file.
;; - C-c d ; will insert a Doxygen comment for the current member.
;; - C-c d m will insert a blank multiline Doxygen comment.
;; - C-c d s will insert a blank singleline Doxygen comment.
;; - C-c d @ will insert grouping comments around the current region.
;;
;; Doxymacs has been tested on and works with:
;; - GNU Emacs 20.7.1, 21.1.1, 21.2.1, 21.2.92.1, 21.3, 21.4.1, 23.1.1
;; - XEmacs 21.1 (patch 14), 21.4 (patches 4-17)
;;
;; If you have success or failure with other version of {X}Emacs, please
;; let the authors know.
;; Change log:
;;
;; 07/03/2010 - feature #1569376: Interactively insert doxygen commands.
;; 19/02/2010 - patch #2954452: Add new documentation style C++!.
;; bug #1862867: Remove trailing whitespace in JavaDoc function
;; template.
;; 18/02/2010 - Support new tparam doxygen command.
;; 10/06/2007 - version 1.8.0
;; 02/02/2007 - bug #1490021: Allow spaces in @param [in] documentation.
;; bug #1496399: Allow for different ways of user-mail-address
;; to be defined.
;; 22/04/2006 - feature #1338245: Add tokens to filladapt to match
;; doxygen markup.
;; - version 1.7.0
;; 04/06/2005 - version 1.6.0
;; 14/04/2005 - Use doxymacs-url-exists-p to wrap the various ways of
;; checking whether a URL exists.
;; - Clean up symbol-near-point hack.
;; 13/04/2005 - feature request #868413: ability to customize the browser
;; doxymacs uses to display documentation.
;; 12/04/2005 - bug #990123: grouping comments do not work.
;; - add some missing doxygen keywords.
;; 01/04/2005 - patch #1024026: use new font-lock-add-keywords function if
;; available.
;; 31/03/2005 - patch #1102042: handle @param[in] etc. constructs
;; 25/01/2003 - remove hard coded version number from comments.
;; - add instructions to avoid byte compiling files.
;; - version 1.5.0
;; 11/01/2003 - feature #665470: C++ style.
;; - fix bug #665099: missing @var fontification.
;; - fix bug #665372: @example not fontified properly.
;; - fix fontification for other keywords as well.
;; - new customisation variable doxymacs command-character
;; which allows for customisation of the character used
;; to introduce Doxygen commands independent of the
;; current style.
;; 05/01/2003 - autoconf-ise.
;; - version 1.4.0
;; 09/12/2002 - turn off buffer modified flag for doxytags to avoid
;; prompting user for killing a modified buffer.
;; 08/12/2002 - move to association lists to support multiple Doxygen
;; generates.
;; 30/11/2002 - apply patch 636146:
;; - several FIXMEs fixed
;; - user-defined "void" types
;; - thanks to Georg Drenkhahn
;; 31/08/2002 - bug #601028 fixed... functions with blank lines in their
;; argument list confused doxymacs-extract-args-list
;; - version 1.3.2
;; 09/05/2002 - fix issues compiling doxymacs_parser.c on Mac OS X.
;; - version 1.3.1
;; 19/11/2001 - doxymacs has been tested on and works with XEmacs 21.4
;; (patch 5) and GNU Emacs 21.1.1
;; 04/11/2001 - add some documentation for default templates.
;; - implement grouping comments (C-c d @)
;; - version 1.3.0
;; 30/09/2001 - doxymacs has been tested on and works with XEmacs 21.4
;; (patch 4)
;; 15/09/2001 - bug #460396 fixed... wrong number of arguments for
;; doxymacs-parm-tempo-element in
;; doxymacs-Qt-function-comment-template
;; - version 1.2.1
;; 26/08/2001 - feature request #454122 (single line member comments) done.
;; - feature request #454123 (key bindings description) done.
;; - clean up template code to make it easier to add new templates
;; and to catch bad settings.
;; - clean up documentation to be more standards conforming.
;; - version 1.2.0
;; 23/08/2001 - fix bug #454563... missing @endlink in fontification,
;; fix @b, @em, @c, @p and @link fontification.
;; - make fontification regexps easier to read.
;; - version 1.1.4
;; 07/07/2001 - make external XML parser work with libxml2. Now requires
;; version 2.3.4 or greater
;; - version 1.1.3
;; 04/07/2001 - GNU Emacs doesn't understand ?: in regexps, so take them out
;; - version 1.1.2
;; 20/06/2001 - fix bug #432837 missing @see keyword
;; - fix bug #432836 Font lock for @ingroup not correct
;; - version 1.1.1
;; 12/06/2001 - add font lock keywords for Doxygen keywords
;; - version 1.1.0
;; 06/06/2001 - fix bug #427660 (mouse selection problems).
;; - version 1.0.0
;; 26/05/2001 - fix bug #427351 (thinks "void" is a parameter) and bug
;; #427350 (can't document constructors/destructors), and
;; generally made the whole doxymacs-find-next-func function
;; much more robust. Small update to default styles when
;; inserting functions that return "void"
;; - version 0.2.1
;; 21/05/2001 - now able to optionally use an "external" XML parser to speed
;; things up.
;; - version 0.2.0
;; 12/05/2001 - fix some bugs on GNU Emacs... tested and works with GNU
;; Emacs 20.7.1
;; - version 0.1.2
;; 09/05/2001 - change C-? to C-c d ?, since hitting DEL also triggers C-?
;; - update progress while parsing XML file
;; - version 0.1.1
;; 07/05/2001 - minor mode thanks to Kris, and default key map.
;; - released as version 0.1.0 (Alpha)
;; 06/05/2001 - Now using tempo templates for the comments... also allow for
;; user defined templates.
;; 29/04/2001 - The doxytags.pl PERL script is no longer necessary, as we can
;; now parse the XML file that doxygen creates directly.
;; 22/04/2001 - Function documentation.
;; 18/04/2001 - Going with Kris' "new style" look up code. It's excellent.
;; - Load tags from URL.
;; 11/04/2001 - added ability to insert blank doxygen comments with either
;; Qt or JavaDoc style.
;; - also did "file" comments
;; 31/03/2001 - added ability to choose which symbol to look up if more than
;; one match
;; - slightly changed the format of the list that
;; doxymacs-get-matches returns
;; 28/03/2001 - added doxymacs to the "tools" customisation group.
;; - removed doxymacs-browser (just use user's default browser)
;; - minor formatting updates
;; 24/03/2001 - initial version. Pretty lame. Need some help.
;; TODO:
;;
;; - better end-user documentation
;; - fix all FIXMEs (of course)
;; - other stuff?
;; Front matter and variables
(provide 'doxymacs)
(require 'custom)
(require 'xml-parse)
(require 'url)
(require 'tempo)
(defconst doxymacs-version "@VERSION@"
"Doxymacs version number")
(defun doxymacs-version ()
"Report the current version of doxymacs in the minibuffer."
(interactive)
(message "Using doxymacs version %s" doxymacs-version))
(defgroup doxymacs nil
"Find documentation created by Doxygen, and create Doxygen comments."
:group 'tools)
(defcustom doxymacs-doxygen-dirs
nil
"List associating pathnames with Doxygen documentation.
Each item on the list is a list of the form (DIR-REGEXP XML URL)
where:
DIR-REGEXP is a regular expression that matches a directory;
XML is the file name or URL of the corresponding Doxygen XML tags; and
URL is the URL of the Doxygen documentation that matches that directory.
For example, if all the files in /home/me/project/foo have their documentation
at http://someplace.com/doc/foo/ and the XML tags file is at
http://someplace.com/doc/foo/foo.xml, and all the files in
/home/me/project/bar have their documentation at
file:///home/me/project/bar/doc/ and the XML tags file is at
/home/me/project/bar/doc/bar.xml, then you would set this list to
'((\"^/home/me/project/foo/\"
\"http://someplace.com/doc/foo/foo.xml\"
\"http://someplace.com/doc/foo/\")
(\"^/home/me/project/bar/\"
\"~/project/bar/doc/bar.xml\"
\"file:///home/me/project/bar/doc/\"))"
:type 'list
:group 'doxymacs)
(defcustom doxymacs-doxygen-style
"@DOXYMACS_DEFAULT_STYLE@"
"The style of comments to insert into code.
See http://www.stack.nl/~dimitri/doxygen/docblocks.html#docblocks for examples
of the various styles.
Must be one of \"JavaDoc\", \"Qt\" \"C++\" or \"C++!\". Setting this variable
to anything else will generate errors."
:type '(radio (const :tag "JavaDoc" "JavaDoc")
(const :tag "Qt" "Qt")
(const :tag "C++" "C++")
(const :tag "C++!" "C++!"))
:group 'doxymacs)
(defcustom doxymacs-command-character
nil
"The character to use to introduce Doxygen commands when inserting comments.
If nil, then use the default dictated by `doxymacs-doxygen-style'. Otherwise,
must be one of \"@\" or \"\\\"."
:type '(choice (const :tag "None" nil)
string)
:group 'doxymacs)
(defcustom doxymacs-use-external-xml-parser
@DOXYMACS_USE_EXTERNAL_XML_PARSER@
"*Use the external (written in C) XML parser or the internal (LISP) parser.
For smallish tag files, you are better off with the internal parser.
For larger tag files, you are better off with the external one.
Set to non-nil to use the external XML parser."
:type '(choice (const :tag "Yes" t)
(const :tag "No" nil))
:group 'doxymacs)
(defcustom doxymacs-external-xml-parser-executable
"@DOXYMACS_PARSER@"
"*Where the external XML parser executable is."
:type 'string
:group 'doxymacs)
(defcustom doxymacs-browse-url-function
'browse-url
"*Function to call to launch a browser to display Doxygen documentation.
This function should take one argument, a string representing the URL to
display."
:type 'function
:group 'doxymacs)
(defcustom doxymacs-blank-multiline-comment-template
nil
"A tempo template to insert for `doxymacs-insert-blank-multiline-comment'.
If nil, then a default template based on the current style as indicated
by `doxymacs-doxygen-style' will be used.
For help with tempo templates, see http://www.lysator.liu.se/~davidk/elisp/"
:type 'list
:group 'doxymacs)
(defcustom doxymacs-blank-singleline-comment-template
nil
"A tempo template to insert for `doxymacs-insert-blank-singleline-comment'.
If nil, then a default template based on the current style as indicated
by `doxymacs-doxygen-style' will be used.
For help with tempo templates, see http://www.lysator.liu.se/~davidk/elisp/"
:type 'list
:group 'doxymacs)
(defcustom doxymacs-file-comment-template
nil
"A tempo template to insert for `doxymacs-insert-file-comment'.
If nil, then a default template based on the current style as indicated
by `doxymacs-doxygen-style' will be used.
For help with tempo templates, see http://www.lysator.liu.se/~davidk/elisp/"
:type 'list
:group 'doxymacs)
(defcustom doxymacs-function-comment-template
nil
"A tempo template to insert for `doxymacs-insert-function-comment'.
If nil, then a default template based on the current style as
indicated by `doxymacs-doxygen-style' will be used. Note that the
function `doxymacs-find-next-func' is available to you... it returns
an assoc list with the function's name, argument list (BUG: may be
incorrect for parameters that require parentheses), and return
value:
(cdr (assoc 'func (doxymacs-find-next-func))) is the function name (string).
(cdr (assoc 'args (doxymacs-find-next-func))) is a list of arguments.
(cdr (assoc 'return (doxymacs-find-next-func))) is the return type (string).
The argument list is a list of strings.
For help with tempo templates, see http://www.lysator.liu.se/~davidk/elisp/"
:type 'list
:group 'doxymacs)
(defcustom doxymacs-void-types
"void"
"String with void-kind variable types. Extend this string if there
are typedefs of void. Example: \"void tVOID\"."
:type 'string
:group 'doxymacs)
(defcustom doxymacs-member-comment-start
nil
"String to insert to start a new member comment.
If nil, use a default one based on the current style as indicated by
`doxymacs-doxygen-style'."
:type '(choice (const :tag "None" nil)
string)
:group 'doxymacs)
(defcustom doxymacs-member-comment-end
nil
"String to insert to end a new member comment.
If nil, use a default one based on the current style as indicated by
`doxymacs-doxygen-style'.
Should be an empty string if comments are terminated by end-of-line."
:type '(choice (const :tag "None" nil)
string)
:group 'doxymacs)
(defcustom doxymacs-group-comment-start
nil
"A string to begin a grouping comment (`doxymacs-insert-grouping-comments').
If nil, then a default template based on the current style as indicated
by `doxymacs-doxygen-style' will be used."
:type '(choice (const :tag "None" nil)
string)
:group 'doxymacs)
(defcustom doxymacs-group-comment-end
nil
"A string to end a grouping comment (`doxymacs-insert-grouping-comments').
If nil, then a default template based on the current style as indicated
by `doxymacs-doxygen-style' will be used."
:type '(choice (const :tag "None" nil)
string)
:group 'doxymacs)
;; End of customisable variables
(defvar doxymacs-tags-buffers nil
"The buffers with our Doxygen tags; a list of the form
'((DIR . BUFFER) (...)) where:
DIR is one of the directories from `doxymacs-doxygen-dirs'; and
BUFFER is the buffer holding the Doxygen tags for that DIR.")
;; The structure of this list has been chosen for ease of use in the
;; completion functions.
(defvar doxymacs-completion-lists nil
"The lists with doxytags completions.
The structure is as follows:
( (dir1 . (symbol-1 . ((description-1a . url-1a) (description-1b . url-1b)))
(symbol-2 . ((description-2a . url-2a))))
... )
where
dir1 is one of the directories from `doxymacs-doxygen-dirs';
symbol-1 is one of the symbols in the associated Doxygen XML file;
description-1a is one of symbol-1's description from the XML file; and
url-1a is the associated URL.")
(defvar doxymacs-current-completion-list nil
"The current list we are building")
(defvar doxymacs-completion-buffer "*Completions*"
"The buffer used for displaying multiple completions.")
;; Minor mode implementation
(defvar doxymacs-mode nil
"nil disables doxymacs, non-nil enables.")
(make-variable-buffer-local 'doxymacs-mode)
(defun doxymacs-mode (&optional arg)
;; All of the following text shows up in the "mode help" (C-h m)
"Minor mode for using/creating Doxygen documentation.
To submit a problem report, request a feature or get support, please
visit doxymacs' homepage at http://doxymacs.sourceforge.net/.
To see what version of doxymacs you are running, enter
`\\[doxymacs-version]'.
In order for `doxymacs-lookup' to work you will need to customise the
variable `doxymacs-doxygen-dirs'.
Key bindings:
\\{doxymacs-mode-map}"
(interactive "P")
(setq doxymacs-mode
(if (null arg)
;; Toggle mode
(not doxymacs-mode)
;; Enable/Disable according to arg
(> (prefix-numeric-value arg) 0)))
(when doxymacs-mode
(when (boundp 'filladapt-token-table)
;; add tokens to filladapt to match doxygen markup
(let ((bullet-regexp (concat "[@\\]"
"\\(param\\(?:\\s-*"
"\\[\\(?:in\\|out\\|in,out\\)\\]\\)?"
"\\s-+\\sw+"
"\\|tparam\\s-+\\sw+"
"\\|return\\|attention\\|note"
"\\|brief\\|li\\|arg\\|remarks"
"\\|invariant\\|post\\|pre"
"\\|todo\\|warning\\|bug"
"\\|deprecated\\|since\\|test\\)")))
(unless (assoc bullet-regexp filladapt-token-table)
(setq filladapt-token-table
(append filladapt-token-table
(list (list bullet-regexp 'bullet)))))))))
;; Keymap
(defvar doxymacs-mode-map (make-sparse-keymap)
"Keymap for doxymacs minor mode.")
(define-key doxymacs-mode-map "\C-cd?"
'doxymacs-lookup)
(define-key doxymacs-mode-map "\C-cdr"
'doxymacs-rescan-tags)
(define-key doxymacs-mode-map "\C-cd\r"
'doxymacs-insert-command)
(define-key doxymacs-mode-map "\C-cdf"
'doxymacs-insert-function-comment)
(define-key doxymacs-mode-map "\C-cdi"
'doxymacs-insert-file-comment)
(define-key doxymacs-mode-map "\C-cdm"
'doxymacs-insert-blank-multiline-comment)
(define-key doxymacs-mode-map "\C-cds"
'doxymacs-insert-blank-singleline-comment)
(define-key doxymacs-mode-map "\C-cd;"
'doxymacs-insert-member-comment)
(define-key doxymacs-mode-map "\C-cd@"
'doxymacs-insert-grouping-comments)
;;;###autoload
(or (assoc 'doxymacs-mode minor-mode-alist)
(setq minor-mode-alist
(cons '(doxymacs-mode " doxy") minor-mode-alist)))
(or (assoc 'doxymacs-mode minor-mode-map-alist)
(setq minor-mode-map-alist
(cons (cons 'doxymacs-mode doxymacs-mode-map)
minor-mode-map-alist)))
;; This stuff has to do with fontification
;; Thanks to Alec Panovici for the idea.
(defconst doxymacs-doxygen-keywords
(list
(list
;; One shot keywords that take no arguments
(concat "\\([@\\\\]\\(brief\\|li\\|\\(end\\)?code\\|sa"
"\\|note\\|\\(end\\)?verbatim\\|return\\|arg\\|fn"
"\\|hideinitializer\\|showinitializer"
;; FIXME
;; How do I get & # < > % to work?
;;"\\|\\\\&\\|\\$\\|\\#\\|<\\|>\\|\\%"
"\\|\\$"
"\\|internal\\|nosubgrouping\\|author\\|date\\|endif"
"\\|invariant\\|post\\|pre\\|remarks\\|since\\|test\\|version"
"\\|\\(end\\)?htmlonly\\|\\(end\\)?latexonly\\|f\\$\\|file"
"\\|\\(end\\)?xmlonly\\|\\(end\\)?manonly\\|property"
"\\|mainpage\\|name\\|overload\\|typedef\\|deprecated\\|par"
"\\|addindex\\|line\\|skip\\|skipline\\|until\\|see"
"\\|endlink\\|callgraph\\|endcond\\|else\\)\\)\\>")
'(0 font-lock-keyword-face prepend))
;; attention, warning, etc. given a different font
(list
"\\([@\\\\]\\(attention\\|warning\\|todo\\|bug\\)\\)\\>"
'(0 font-lock-warning-face prepend))
;; keywords that take a variable name as an argument
(list
(concat "\\([@\\\\]\\(param\\(?:\\s-*\\[\\(?:in\\|out\\|in,out\\)\\]\\)?"
"\\|tparam\\|a\\|namespace\\|relates\\(also\\)?"
"\\|var\\|def\\)\\)\\s-+\\(\\sw+\\)")
'(1 font-lock-keyword-face prepend)
'(4 font-lock-variable-name-face prepend))
;; keywords that take a type name as an argument
(list
(concat "\\([@\\\\]\\(class\\|struct\\|union\\|exception\\|enum"
"\\|throw\\|interface\\|protocol\\)\\)\\s-+\\(\\(\\sw\\|:\\)+\\)")
'(1 font-lock-keyword-face prepend)
'(3 font-lock-type-face prepend))
;; keywords that take a function name as an argument
(list
"\\([@\\\\]retval\\)\\s-+\\([^ \t\n]+\\)"
'(1 font-lock-keyword-face prepend)
'(2 font-lock-function-name-face prepend))
;; bold
(list
"\\([@\\\\]b\\)\\s-+\\([^ \t\n]+\\)"
'(1 font-lock-keyword-face prepend)
'(2 (quote bold) prepend))
;; code
(list
"\\([@\\\\][cp]\\)\\s-+\\([^ \t\n]+\\)"
'(1 font-lock-keyword-face prepend)
'(2 (quote underline) prepend))
;; italics/emphasised
(list
"\\([@\\\\]e\\(m\\)?\\)\\s-+\\([^ \t\n]+\\)"
'(1 font-lock-keyword-face prepend)
'(3 (quote italic) prepend))
;; keywords that take a list
(list
"\\([@\\\\]ingroup\\)\\s-+\\(\\(\\sw+\\s-*\\)+\\)\\s-*$"
'(1 font-lock-keyword-face prepend)
'(2 font-lock-string-face prepend))
;; one argument that can contain arbitrary non-whitespace stuff
(list
(concat "\\([@\\\\]\\(link\\|copydoc\\|xrefitem"
"\\|if\\(not\\)?\\|elseif\\)\\)"
"\\s-+\\([^ \t\n]+\\)")
'(1 font-lock-keyword-face prepend)
'(4 font-lock-string-face prepend))
;; one optional argument that can contain arbitrary non-whitespace stuff
(list
"\\([@\\\\]\\(cond\\|dir\\)\\(\\s-+[^ \t\n]+\\)?\\)"
'(1 font-lock-keyword-face prepend)
'(3 font-lock-string-face prepend t))
;; one optional argument with no space between
(list
"\\([@\\\\]\\(~\\)\\([^ \t\n]+\\)?\\)"
'(1 font-lock-keyword-face prepend)
'(3 font-lock-string-face prepend t))
;; one argument that has to be a filename
(list
(concat "\\([@\\\\]\\(example\\|\\(dont\\)?include\\|includelineno"
"\\|htmlinclude\\|verbinclude\\)\\)\\s-+"
"\\(\"?[~:\\/a-zA-Z0-9_. ]+\"?\\)")
'(1 font-lock-keyword-face prepend)
'(4 font-lock-string-face prepend))
;; dotfile <file> ["caption"]
(list
(concat "\\([@\\\\]dotfile\\)\\s-+"
"\\(\"?[~:\\/a-zA-Z0-9_. ]+\"?\\)\\(\\s-+\"[^\"]+\"\\)?")
'(1 font-lock-keyword-face prepend)
'(2 font-lock-string-face prepend)
'(3 font-lock-string-face prepend t))
;; image <format> <file> ["caption"] [<sizeindication>=<size>]
(list
"\\([@\\\\]image\\)\\s-+\\(html\\|latex\\)\\s-+\\(\"?[~:\\/a-zA-Z0-9_. ]+\"?\\)\\(\\s-+\"[^\"]+\"\\)?\\(\\s-+\\sw+=[0-9]+\\sw+\\)?"
'(1 font-lock-keyword-face prepend)
'(2 font-lock-string-face prepend)
'(3 font-lock-string-face prepend)
'(4 font-lock-string-face prepend t)
'(5 font-lock-string-face prepend t))
;; one argument that has to be a word
(list
(concat "\\([@\\\\]\\(addtogroup\\|defgroup\\|weakgroup"
"\\|page\\|anchor\\|ref\\|section\\|subsection"
"\\)\\)\\s-+\\(\\sw+\\)")
'(1 font-lock-keyword-face prepend)
'(3 font-lock-string-face prepend))))
(defun doxymacs-font-lock ()
"Turn on font-lock for Doxygen keywords."
;; FIXME How do I turn *off* font-lock for Doxygen keywords?
(interactive)
(if (functionp 'font-lock-add-keywords)
;; Use new (proper?) font-lock-add-keywords function
(font-lock-add-keywords nil doxymacs-doxygen-keywords)
;; Use old-school way
(let ((old (if (eq (car-safe font-lock-keywords) t)
(cdr font-lock-keywords)
font-lock-keywords)))
(setq font-lock-keywords (append old doxymacs-doxygen-keywords)))))
;;These functions have to do with looking stuff up in doxygen generated
;;documentation
;; Utility functions to look up filenames in the various association lists
;; we have
(defun doxymacs-filename-to-element (f a)
"Lookup filename in one of our association lists and return associated
element"
(catch 'done
(while a
(if (string-match (caar a) f)
(throw 'done
(cdar a))
(setq a (cdr a))))))
(defun doxymacs-filename-to-xml (f)
"Lookup filename in `doxymacs-doxygen-dirs' and return associated XML tags
file."
(let ((xml-url (doxymacs-filename-to-element f doxymacs-doxygen-dirs)))
(if xml-url
(car xml-url))))
(defun doxymacs-filename-to-url (f)
"Lookup filename in `doxymacs-doxygen-dirs' and return associated Doxygen
documentation URL root."
(let ((xml-url (doxymacs-filename-to-element f doxymacs-doxygen-dirs)))
(if xml-url
(cadr xml-url))))
(defun doxymacs-filename-to-buffer (f)
"Lookup filename in `doxymacs-tags-buffers' and return associated buffer."
(doxymacs-filename-to-element f doxymacs-tags-buffers))
(defun doxymacs-filename-to-completion-list (f)
"Lookup filename in `doxymacs-completion-lists' and return associated
completion list."
(doxymacs-filename-to-element f doxymacs-completion-lists))
(defun doxymacs-filename-to-dir (f)
"Lookup filename in `doxymacs-doxygen-dirs' and return associated dir."
(catch 'done
(let ((dirs doxymacs-doxygen-dirs))
(while dirs
(if (string-match (caar dirs) f)
(throw 'done
(caar dirs))
(setq dirs (cdr dirs)))))))
(defun doxymacs-set-dir-element (dir l e)
"Set the element associated with dir in l to e."
(catch 'done
(while l
(let ((pair (car l)))
(if (string= (car pair) dir)
(throw 'done
(setcdr pair e))
(setq l (cdr l)))))))
(defun doxymacs-set-tags-buffer (dir buffer)
"Set the buffer associated with dir in `doxymacs-tags-buffers' to the given
buffer."
(doxymacs-set-dir-element dir doxymacs-tags-buffers buffer))
(defun doxymacs-set-completion-list (dir comp-list)
"Set the completion list associated with dir in `doxymcas-completion-lists'
to comp-list."
(doxymacs-set-dir-element dir doxymacs-completion-lists comp-list))
(defun doxymacs-url-exists-p (url)
"Return t iff the URL exists."
(let* ((urlobj (url-generic-parse-url url))
(type (url-type urlobj))
(exists nil))
(cond
((equal type "http")
(cond
;; Try url-file-exists, if it exists
((fboundp 'url-file-exists)
(setq exists (url-file-exists url)))
;; Otherwise, try url-file-exists-p (newer url.el)
((fboundp 'url-file-exists-p)
(setq exists (url-file-exists-p url)))
;; Otherwise, try wget
((executable-find (if (eq system-type 'windows-nt) "wget.exe" "wget"))
(if (string-match "200 OK"
(shell-command-to-string
(concat "wget -S --spider " url)))
(setq exists t)))
;; Otherwise, try lynx
((executable-find (if (eq system-type 'windows-nt) "lynx.exe" "lynx"))
(if (string-match "200 OK"
(shell-command-to-string
(concat "lynx -head -source " url)))
(setq exists t)))
;; Give up.
(t (error "Could not find url-file-exists, url-file-exists-p, wget or lynx"))))
((equal type "file")
(setq exists (file-exists-p (url-filename urlobj))))
(t (error (concat "Scheme " type " not supported for URL " url))))
exists))
(defun doxymacs-load-tags (f)
"Loads a Doxygen generated XML tags file into the buffer *doxytags*."
(let* ((tags-buffer (doxymacs-filename-to-buffer f))
(dir (doxymacs-filename-to-dir f))
(xml (doxymacs-filename-to-xml f)))
(if (and xml dir)
(if (or (eq tags-buffer nil)
(eq (buffer-live-p tags-buffer) nil))
(let ((new-buffer (generate-new-buffer "*doxytags")))
(if tags-buffer
;; tags-buffer is non-nil, which means someone
;; killed the buffer... so reset it
(doxymacs-set-tags-buffer dir new-buffer)
;; Otherwise add to list
(setq doxymacs-tags-buffers
(cons (cons dir new-buffer) doxymacs-tags-buffers)))
(message (concat "Loading " xml "..."))
(let ((currbuff (current-buffer)))
(if (file-regular-p xml)
;;It's a regular file, so just grab it.
(progn
(set-buffer new-buffer)
(insert-file-contents xml))
;; Otherwise, try and grab it as a URL
(progn
(if (doxymacs-url-exists-p xml)
(progn
(set-buffer new-buffer)
(url-insert-file-contents xml)
(set-buffer-modified-p nil))
(progn
(kill-buffer new-buffer)
(set-buffer currbuff)
(error (concat
"Tag file " xml " not found."))))))
(set-buffer currbuff))))
;; Couldn't find this file in doxymacs-doxygen-dirs
(error (concat "File " (buffer-file-name)
" does not match any directories in"
" doxymacs-doxygen-dirs.")))))
(defun doxymacs-add-to-completion-list (symbol desc url)
"Add a symbol to our completion list, along with its description and URL."
(let ((check (assoc symbol doxymacs-current-completion-list)))
(if check
;; There is already a symbol with the same name in the list
(if (not (assoc desc (cdr check)))
;; If there is not yet a symbol with this desc, add it
;; FIXME: what to do if there is already a symbol??
(setcdr check (cons (cons desc url)
(cdr check))))
;; There is not yet a symbol with this name in the list
(setq doxymacs-current-completion-list
(cons (cons symbol (list (cons desc url)))
doxymacs-current-completion-list)))))
(defun doxymacs-fill-completion-list-with-external-parser (f)
"Use external parser to parse Doxygen XML tags file and get the
completion list."
(doxymacs-load-tags f)
(let ((currbuff (current-buffer))
(dir (doxymacs-filename-to-dir f))
(comp-list (doxymacs-filename-to-completion-list f))
(tags-buffer (doxymacs-filename-to-buffer f)))
(set-buffer tags-buffer)
(goto-char (point-min))
(doxymacs-set-completion-list dir nil)
(message (concat
"Executing external process "
doxymacs-external-xml-parser-executable
"..."))
(let ((status (call-process-region
(point-min) (point-max)
doxymacs-external-xml-parser-executable
t t)))
(if (eq status 0)
(progn
(goto-char (point-min))
(message "Reading completion list...")
(let ((new-list (read (current-buffer))))
(if comp-list
;; Replace
(doxymacs-set-completion-list dir new-list)
;; Add
(setq doxymacs-completion-lists
(cons (cons dir new-list)
doxymacs-completion-lists))))
(message "Done.")
(set-buffer-modified-p nil)
(kill-buffer tags-buffer)
(set-buffer currbuff))
(progn
(switch-to-buffer tags-buffer)
(message (concat
"There were problems parsing "
(doxymacs-filename-to-xml f) ".")))))))
(defun doxymacs-xml-progress-callback (amount-done)
"Let the user know how far along the XML parsing is."
(message (concat "Parsing ... " (format "%0.1f" amount-done) "%%")))
(defun doxymacs-fill-completion-list-with-internal-parser (f)
"Load and parse the tags from the *doxytags* buffer, constructing our
`doxymacs-completion-list' from it using the internal XML file parser."
(doxymacs-load-tags f)
(let ((currbuff (current-buffer))
(dir (doxymacs-filename-to-dir f))
(tags-buffer (doxymacs-filename-to-buffer f)))
(set-buffer tags-buffer)
(goto-char (point-min))
(setq doxymacs-current-completion-list nil)
(let ((xml (read-xml 'doxymacs-xml-progress-callback))) ;Parse the file
(let* ((compound-list (xml-tag-children xml))
(num-compounds (length compound-list))
(curr-compound-num 0))
(if (not (string= (xml-tag-name xml) "tagfile"))
(error (concat "Invalid tag file: " (doxymacs-filename-to-xml f)))
;; Go through the compounds, adding them and their members to the
;; completion list.
(while compound-list
(let* ((curr-compound (car compound-list))
(compound-name (cadr (xml-tag-child curr-compound "name")))
(compound-kind (xml-tag-attr curr-compound "kind"))
(compound-url (cadr
(xml-tag-child curr-compound "filename")))
(compound-desc (concat compound-kind " " compound-name)))
;; Work around apparent bug in Doxygen 1.2.18
(if (not (string-match "\\.html$" compound-url))
(setq compound-url (concat compound-url ".html")))
;; Add this compound to our completion list for this directory
(doxymacs-add-to-completion-list compound-name
compound-desc
compound-url)
;; Add its members
(doxymacs-add-compound-members curr-compound
compound-name
compound-url)
;; On to the next compound
(message (concat
"Building completion table... "
(format "%0.1f"
(* (/
(float curr-compound-num)
(float num-compounds))
100))
"%%"))
(setq curr-compound-num (1+ curr-compound-num))
(setq compound-list (cdr compound-list)))))))
(if (doxymacs-filename-to-completion-list f)
;; Replace
(doxymacs-set-completion-list dir doxymacs-current-completion-list)
;; Add
(setq doxymacs-completion-lists
(cons (cons dir doxymacs-current-completion-list)
doxymacs-completion-lists)))
(setq doxymacs-current-completion-list nil)
(message "Done.")
;; Don't need the doxytags buffer anymore
(set-buffer-modified-p nil)
(kill-buffer tags-buffer)
(set-buffer currbuff)))
(defun doxymacs-add-compound-members (compound compound-name compound-url)
"Get the members of the given compound"
(let ((children (xml-tag-children compound)))
;; Run through the children looking for ones with the "member" tag
(while children
(let* ((curr-child (car children)))
(if (string= (xml-tag-name curr-child) "member")
;; Found a member. Throw it on the list.
(let* ((member-name (cadr (xml-tag-child curr-child "name")))
(member-anchor (cadr (xml-tag-child curr-child "anchor")))
(member-url (concat compound-url "#" member-anchor))
(member-args (if (cdr (xml-tag-child curr-child "arglist"))
(cadr (xml-tag-child curr-child "arglist"))
""))
(member-desc (concat compound-name "::"
member-name member-args)))
(doxymacs-add-to-completion-list member-name
member-desc
member-url)))
(setq children (cdr children))))))
(defun doxymacs-display-url (root url)
"Displays the given match."
(apply doxymacs-browse-url-function (list (concat root "/" url))))
;; Some versions of GNU Emacs don't have symbol-near-point apparently
;; stolen from browse-cltl2.el, and in turn:
;; stolen from XEmacs 19.15 syntax.el
(defun doxymacs-symbol-near-point ()
"Return the first textual item to the nearest point."
(if (fboundp 'symbol-near-point)
(symbol-near-point)
;;alg stolen from etag.el
(save-excursion
(if (not (memq (char-syntax (preceding-char)) '(?w ?_)))
(while (not (looking-at "\\sw\\|\\s_\\|\\'"))
(forward-char 1)))
(while (looking-at "\\sw\\|\\s_")
(forward-char 1))
(if (re-search-backward "\\sw\\|\\s_" nil t)
(regexp-quote
(progn (forward-char 1)
(buffer-substring (point)
(progn (forward-sexp -1)
(while (looking-at "\\s'")
(forward-char 1))
(point)))))
nil))))
(defun doxymacs-assocl (key alist)
(let ((r '()))
(dolist (x alist r)
(if (string-match-p key (car x))
(add-to-list 'r x)))))
(defun doxymacs-sort-alist (alist f)
(let ((sorted-keys (sort (mapcar 'car alist) f))
(sorted-alist-copy '()))
(dolist (x sorted-keys sorted-alist-copy)
(add-to-list 'sorted-alist-copy (assoc x alist) t))))