oni-php: Add function that makes ‘comment-dwim’ add doc comments

This checks to see if point is right before a function and if so adds a
documentation comment. Otherwise it calls to the original ‘comment-dwim’ to do
the right thing for that particular place.

oni-php/oni-php.el

@@ -4,7 +4,7 @@
 
 ;; Author: Tom Willemse <tom@ryuslash.org>
 ;; Keywords: local
-;; Version: 2025.0124.124542
+;; Version: 2025.0210.125238
 ;; Package-Requires: (php-mode oni-yasnippet oni-flycheck oni-company oni-hydra ggtags fic-mode company-php)
 
 ;; This program is free software; you can redistribute it and/or modify
@@ -111,9 +111,32 @@ Do the insert N times."
       (self-insert-command N)
     (dotimes (_ N) (insert "->"))))
 
+(defun oni-php-doc-comment ()
+  "Insert a PHP documentation comment at point."
+  (interactive)
+  (let ((start (point)))
+    (insert "/**\n * ")
+    (let ((insert-marker (point-marker)))
+      (insert "\n */")
+      (indent-region start (point))
+      (goto-char insert-marker))))
+
+(defun oni-php-comment-dwim (func &rest args)
+  "See if a PHP documentation comment should be added and add it.
+Otherwise call FUNC with ARGS. This is meant as advice around
+‘comment-dwim’ to make it smarter for PHP code."
+  (if (and (derived-mode-p 'php-mode)
+           (looking-back (rx blank) (line-beginning-position))
+           (looking-at (rx (minimal-match (zero-or-more (any whitespace "\n")))
+                           (regexp php-beginning-of-defun-regexp))))
+      (oni-php-doc-comment)
+    (apply func args)))
+
 (defhydra php-mode-hydra (:color blue)
   ("a" align-current "Align current selection"))
 
+(advice-add 'comment-dwim :around #'oni-php-comment-dwim)
+
 (add-hook 'php-mode-hook #'oni-php--set-require-final-newline)
 (add-hook 'php-mode-hook #'oni-php--whitespace-mode)
 (add-hook 'php-mode-hook 'company-mode)