Fixing copyright and flymake complaints.

4 files changed, 103 insertions, 38 deletions

diff --git a/wiki-engine.el b/wiki-engine.el
index 74dbe15..c4de2e7 100644
--- a/wiki-engine.el
+++ b/wiki-engine.el
@@ -22,7 +22,7 @@
 ;;; Commentary:
 
 ;; client to wiki engines, wiki server software. Each engine defines
-;; how emacs interacts with the remote server, including how to
+;; how Emacs interacts with the remote server, including how to
 ;; construct a url to fetch from.
 
 ;;; Code:
@@ -40,70 +40,87 @@
     (error "Nil wiki-site or wiki-title!"))
   (wiki-engine-html-url wiki-site wiki-title))
 
-(defun wiki-engine-mediawiki-fetch (wiki-site title)
+
+(defun wiki-engine-wiki-url (site title)
+  "Construct the url to fetch wiki of TITLE from SITE."
+  (let* ((site-info (alist-get site wiki-sites))
+         (engine (plist-get site-info :engine))
+         (base-url (plist-get site-info :base-url)))
+    (pcase engine
+      ('mediawiki (format "%s%s?action=raw" base-url title))
+      ('moinmoin (format "%s%s?action=raw" base-url title))
+      ('oddmuse (format "%s?action=download;id=%s" base-url title))
+      (_ (error "Unknown engine: %s" engine)))))
+
+(defun wiki-engine-mediawiki-fetch (site-id title)
   "Fetch a mediawiki entry describing TITLE.
 
-The site handle is passed as a symbol WIKI-SITE."
-  (let ((wiki-site-info (alist-get wiki-site wiki-sites)))
+The site handle is passed as a symbol SITE-ID."
+  (let ((wiki-site-info (alist-get site-id wiki-sites)))
     (cl-assert (eq (plist-get wiki-site-info :engine) 'mediawiki))
     (when (string-empty-p title) (setq title "Main Page"))
     (unless (and wiki-fetch-prefer-local
                  (wiki-find-file
                   title
-                  (wiki-locate-dir wiki-site)))
+                  (wiki-locate-dir site-id)))
       (wiki-fetch-url
        (format "%s%s?action=raw"
                (plist-get wiki-site-info :base-url)
                title)
-       (wiki-locate-dir wiki-site)
+       (wiki-locate-dir site-id)
        (lambda ()
          (wiki-mode)
-         (setq-local wiki-site wiki-site
+         (setq-local wiki-site site-id
                      wiki-title title)
          )
        ))))
 
-(defun wiki-engine-oddmuse-fetch (wiki-site title)
-  (let ((wiki-site-info (alist-get wiki-site wiki-sites)))
+(defun wiki-engine-oddmuse-fetch (site-id title)
+  "Fetch an oddmuse entry describing TITLE.
+
+The site handle is passed as a symbol SITE-ID."
+  (let ((wiki-site-info (alist-get site-id wiki-sites)))
     (cl-assert (eq (plist-get wiki-site-info :engine) 'oddmuse))
     (unless (and wiki-fetch-prefer-local
                  (wiki-find-file
                   title
-                  (wiki-locate-dir wiki-site)))
+                  (wiki-locate-dir site-id)))
       (wiki-fetch-url
        (format "%s?action=download;id=%s"
                (plist-get wiki-site-info :base-url)
                title)
-       (wiki-locate-dir wiki-site)
+       (wiki-locate-dir site-id)
        (lambda ()
          (wiki-mode)
-         (setq-local wiki-site wiki-site
+         (setq-local wiki-site site-id
                      wiki-title title)
          )
        title))))
 
-(defun wiki-engine-moinmoin-fetch (wiki-site title)
-  (let ((wiki-site-info (alist-get wiki-site wiki-sites)))
+(defun wiki-engine-moinmoin-fetch (site-id title)
+  "Fetch a moinmoin entry describing TITLE.
+
+The site handle is passed as a symbol SITE-ID."
+  (let ((wiki-site-info (alist-get site-id wiki-sites)))
     (cl-assert (eq (plist-get wiki-site-info :engine) 'moinmoin))
     (unless (and wiki-fetch-prefer-local
                  (wiki-find-file
                   title
-                  (wiki-locate-dir wiki-site)))
+                  (wiki-locate-dir site-id)))
       (wiki-fetch-url
        (format "%s%s?action=raw"
                (plist-get wiki-site-info :base-url)
                title)
-       (wiki-locate-dir wiki-site)
+       (wiki-locate-dir site-id)
        (lambda ()
          (wiki-mode)
-         (setq-local wiki-site wiki-site
-                     wiki-title title)
-         )
+         (setq-local wiki-site site-id
+                     wiki-title title))
        title))))
 
-(defun wiki-locate-dir (wiki-site)
-  "Locate the directory for a WIKI-SITE."
-  (expand-file-name (format "%s" wiki-site) wiki-local-dir))
+(defun wiki-locate-dir (site-id)
+  "Locate the directory for a SITE-ID."
+  (expand-file-name (format "%s" site-id) wiki-local-dir))
 
 (defun wiki-find-file (title &optional dir create-if-not-exists
                              extension)
@@ -111,7 +128,8 @@ The site handle is passed as a symbol WIKI-SITE."
 
 Returns the file-name if success, and nil otherwise. If
 CREATE-IF-NOT-EXISTS is non-nil, creates the file is not found.
-DIR defaults to `default-directory'."
+DIR defaults to `default-directory'.
+EXTENSION is the file extension."
   (interactive (list (read-file-name "Find wiki file: ")))
   (unless dir (setq dir default-directory))
   (let ((file-name (expand-file-name
@@ -127,10 +145,12 @@ DIR defaults to `default-directory'."
 (defalias #'wiki-local-fetch #'wiki-find-file)
 
 (defun wiki-engine-fetcher (wiki-site-info)
+  "Return the fetcher for the engine of WIKI-SITE-INFO."
   (intern (format "wiki-engine-%s-fetch"
                   (plist-get wiki-site-info :engine))))
 
 (defmacro defun-wiki-fetchers ()
+  "Defines all wiki fetcher functions."
   (cons 'progn
         (mapcar
          (lambda (pair)
diff --git a/wiki-faces.el b/wiki-faces.el
index f0ea4a6..d55172e 100644
--- a/wiki-faces.el
+++ b/wiki-faces.el
@@ -1,6 +1,6 @@
 ;;; wiki-faces.el -- faces for wiki-mode -*- lexical-binding: t -*-
 
-;; Copyright (C) 2023 Free Software Foundation.
+;; Copyright (C) 2023  Free Software Foundation, Inc.
 
 ;; Author: Yuchen Pei <id@ypei.org>
 ;; Package-Requires: ((emacs "28.2"))
diff --git a/wiki-markup.el b/wiki-markup.el
index f0f26cb..645c71e 100644
--- a/wiki-markup.el
+++ b/wiki-markup.el
@@ -1,6 +1,6 @@
 ;;; wiki-markup.el -- A wikitext mode -*- lexical-binding: t -*-
 
-;; Copyright (C) 2023 Free Software Foundation.
+;; Copyright (C) 2023  Free Software Foundation, Inc.
 
 ;; Author: Yuchen Pei <id@ypei.org>
 ;; Package-Requires: ((emacs "28.2"))
@@ -26,6 +26,7 @@
 
 ;;; Code:
 (require 'wiki-faces)
+(require 'wiki-utils)
 
 (defvar wiki-url-re "https?://[^ |}]+")
 
@@ -78,7 +79,9 @@
 (defvar-local wiki-title nil
   "The title of the current wiki buffer.")
 (defun wiki-follow-wikilink-action (data)
-  "Button action to follow a wikilink"
+  "Button action to follow a wikilink.
+
+The button data is passed as DATA."
   (funcall (wiki-site-fetcher wiki-site) (alist-get 'target data)))
 
 (defun wiki-guess-site ()
@@ -101,12 +104,16 @@ This can be overriden with .dir-locals.el."
     (setq-local wiki-title (file-name-base (buffer-file-name)))))
 
 (defun wiki-outline-level ()
+  "Determines the outline header level in `outline-mode'."
   (when (looking-at "\\(=+\\).*[^=]\\(=+\\)\\ *$")
     (min (length (match-string 1))
          (length (match-string 2))
          6)))
 
 (defun wiki-do-refs (limit)
+  "Process ref tags.
+
+LIMIT is the limit of the search, used for `font-lock-keywords'."
   (let ((ref-counter 0))
     (while (re-search-forward "<ref\\([^>]*\\)>" limit t)
       (let ((start (match-beginning 0))
@@ -130,13 +137,16 @@ This can be overriden with .dir-locals.el."
                (goto-char end))
               (t (goto-char next-start)))))))
 
+;; TODO: complete this function.
 (defun wiki-set-template-face (limit)
-  "Set template faces."
+  "Set template faces.
+
+LIMIT is the limit of the search, used for `font-lock-keywords'."
   (while (search-forward "{{" limit t)
     (save-excursion
       (let* ((name-start (point))
              ;; (visible-start name-start)
-             (start (progn (backward-char 2) (point)))
+             ;; (start (progn (backward-char 2) (point)))
              (end (progn (forward-sexp) (point)))
              (visible-end (- end 2))
              (name-end (progn
@@ -154,8 +164,12 @@ This can be overriden with .dir-locals.el."
       )
     ))
 
+;; TODO: complete this function.
 ;; We assume the arg name cannot contain (nested) templates
 (defun wiki-do-one-template-arg (limit)
+  "Process one template arg.
+
+LIMIT is the limit of the search, used for `font-lock-keywords'."
   (let ((found (re-search-forward "|\\ *\\([^|= \t\n]+\\ *[=|]\\)"
                                   limit 'move))
         (name-start (match-beginning 1))
@@ -184,6 +198,9 @@ This can be overriden with .dir-locals.el."
 
 ;; Like `org-do-emphasis-faces'
 (defun wiki-do-emphasis-faces (limit)
+  "Fix emphasis faces of mediawiki markup.
+
+LIMIT is the limit of the search, used for `font-lock-keywords'."
   (while (re-search-forward "\\(''+\\)[^ \t\n].*?[^ \t\n']\\(''+\\)" limit t)
     (let ((start (match-beginning 0))
           (end (match-end 0)))
@@ -194,7 +211,12 @@ This can be overriden with .dir-locals.el."
         ))))
 
 ;; Like `org-activate-links'
+;; TODO: support more types, e.g. interwiki and anchor links.
 (defun wiki-activate-links (link-re type limit)
+  "Activate links in wiki markup match LINK-RE(gexp) of link TYPE.
+
+LIMIT is the limit of the search, used for `font-lock-keywords'.
+Currently supported types are `internal' and `external'."
   (save-excursion
     (goto-char (point-min))
     (while (re-search-forward link-re limit t)
@@ -227,15 +249,25 @@ This can be overriden with .dir-locals.el."
         ))))
 
 (defun wiki-browse-url-action (data)
+  "Call `browse-url' on the button DATA."
   (browse-url (alist-get 'target data)))
 
 (defun wiki-activate-internal-links (limit)
+  "Activate internal links in mediawiki markup.
+
+LIMIT is the limit of the search, used for `font-lock-keywords'."
   (wiki-activate-links wiki-internal-link-re 'internal limit))
 
 (defun wiki-activate-external-links (limit)
+  "Activate external links in mediawiki markup.
+
+LIMIT is the limit of the search, used for `font-lock-keywords'."
   (wiki-activate-links wiki-external-link-re 'external limit))
 
 (defun wiki-activate-raw-links (limit)
+  "Activate raw url links in mediawiki markup.
+
+LIMIT is the limit of the search, used for `font-lock-keywords'."
   (wiki-activate-links (format "\\(%s\\)" wiki-url-re) 'external limit))
 
 (define-derived-mode wiki-mode outline-mode "Wiki"
@@ -261,11 +293,12 @@ This can be overriden with .dir-locals.el."
               imenu-space-replacement nil)
   )
 
-(defun set-wiki-site (wiki-site)
+(defun set-wiki-site (site)
+  "Set `wiki-site' to SITE."
   (interactive (list
                 (completing-read "Set wiki site: "
                                  (mapcar 'car wiki-sites))))
-  (setq-local wiki-site (intern wiki-site)))
+  (setq-local wiki-site (intern site)))
 
 (add-hook 'wiki-mode-hook 'wiki-guess-site)
 (add-hook 'wiki-mode-hook 'wiki-guess-title)
diff --git a/wiki-utils.el b/wiki-utils.el
index ae61d4d..257db5d 100644
--- a/wiki-utils.el
+++ b/wiki-utils.el
@@ -1,6 +1,6 @@
 ;;; wiki-utils.el -- wiki utility functions -*- lexical-binding: t -*-
 
-;; Copyright (C) 2023 Free Software Foundation.
+;; Copyright (C) 2023  Free Software Foundation, Inc.
 
 ;; Author: Yuchen Pei <id@ypei.org>
 ;; Package-Requires: ((emacs "28.2"))
@@ -31,13 +31,14 @@
   "Path to local directory of wiki files.")
 
 (defvar wiki-fetch-prefer-local t
-  "If non-nil, visit the local file if exists when instructed for
-fetching.")
+  "If non-nil, visit the local file if exists when fetching.")
 
 (defun wiki-fetch-url (url dir &optional callback title)
-  "Fetch URL asynchronously.
+  "Fetch URL asynchronously to a file in DIR.
 
-Then calls CALLBACK which is a closure taking no argument."
+Then call CALLBACK which is a closure taking no argument.
+
+A non-nil TITLE overrides title inferred from the url."
   (interactive "sURL: ")
   (let ((file-name (expand-file-name
                     (or title (wiki-make-file-name-from-url url))
@@ -49,6 +50,9 @@ Then calls CALLBACK which is a closure taking no argument."
   )
 
 (defun wiki-fetch-url-save-and-switch (status file-name)
+  "Fetch url to FILE-NAME if STATUS is ok.
+
+And switch to the corresponding buffer."
   (when (plist-get status :error)
     (error "Wiki fetch failed: %s" (plist-get status :error)))
   (wiki-delete-http-header)
@@ -65,13 +69,20 @@ Then calls CALLBACK which is a closure taking no argument."
   )
 
 (defun wiki-delete-http-header ()
+  "Delete the http header in current buffer.
+
+Assuming the current buffer to be a `url-retrieve' response buffer."
   (delete-region (point-min) (progn (wiki-skip-http-header) (point))))
 
 (defun wiki-skip-http-header ()
+  "Skip the http header in current buffer.
+
+Assuming the current buffer to be a `url-retrieve' response buffer."
   (goto-char (point-min))
   (re-search-forward "\r?\n\r?\n"))
 
 (defun wiki-make-file-name-from-url (url)
+  "Make a file name from URL."
   (file-name-nondirectory
    (directory-file-name
     (car (url-path-and-query (url-generic-parse-url
@@ -146,9 +157,10 @@ Each item is in the form of (identifier . properties), where
 identifier is a symbol, and properties is a plist of the site.
 One of the sites is (local), meaning a local filesystem.")
 
-(defun wiki-site-fetcher (wiki-site)
-  (if wiki-site
-      (intern (format "wiki-%s-fetch" wiki-site))
+(defun wiki-site-fetcher (site-id)
+  "Return the fetcher function for wiki site with SITE-ID."
+  (if site-id
+      (intern (format "wiki-%s-fetch" site-id))
     'wiki-find-file))
 
 (provide 'wiki-utils)