Defining Functions: Arguments and Docstrings

1. What is a Function?

Before we dive into the syntax, let's establish a clear concept of what a function is in programming. At its core, a function is a named, reusable piece of code that performs a specific task. Key characteristics include:

• Reusability: You define it once and can execute it many times from different parts of your code.
• Inputs (Arguments): It can accept values, called arguments, that influence its behavior.
• A Body: It contains the set of instructions to be executed.
• An Output (Return Value): It typically produces a result that can be used by other code.

To get a concise overview of these concepts, let's watch a short segment from a video by System Crafters.

2. The Anatomy of a Function Definition

In Emacs Lisp, we define a named function using the defun macro. The term is short for "define function". Its structure is a classic example of a Lisp S-expression.

The general syntax is:

(defun function-name (argument-list)
  "Documentation string (docstring)."
  (function-body-expressions...))

Let's break this down:

1. defun: A symbol that tells Emacs you are defining a function. defun is a special form, meaning it doesn't evaluate its arguments in the usual way. For instance, it knows that function-name is the name you're assigning, not a variable to be evaluated.
2. function-name: A symbol that will be the name of your function. By convention, function names in Elisp use kebab-case.
3. (argument-list): An empty or non-empty list of symbols that will serve as parameters (or arguments) for your function. These are placeholders for the values you'll provide when you call the function.
4. "Documentation string...": An optional, but highly recommended, string that describes what the function does. We'll cover this in detail shortly.
5. (function-body-expressions...): One or more Elisp expressions that make up the body of the function. When the function is called, these expressions are evaluated in order. The value of the last expression evaluated is the function's return value.

Now, let's see this syntax in action.

3. Documenting Your Work: The Docstring

Your experience as a professional writer has shown that clear communication is paramount. In programming, docstrings are the primary form of such communication. They explain the "what" and "how" of a function to other programmers and, just as importantly, to your future self. Emacs has a strong culture of documentation, and its built-in help system is powered by these docstrings.

A docstring is simply a string literal that appears immediately after the argument list in a defun.

There are a few important conventions for writing good docstrings:

• The first line should be a complete sentence that summarizes the function's purpose.
• Write in the imperative voice (e.g., "Return the value..." instead of "Returns the value...").
• When referring to an argument from the argument list, capitalize its name. For example, (defun greet (NAME) "Print a greeting for NAME.").

You can view any function's docstring using the command C-h f (describe-function). This is an invaluable tool for exploring Emacs.

The next video clip provides a practical guide to writing and formatting docstrings, including how Emacs can help you wrap long lines.

4. Practical Application: A Helper for Writers

Now it's time to write your first function. Open your *scratch* buffer in Emacs. We'll create a simple function that takes a string (a word or phrase) and wraps it in asterisks, as one might do for emphasis in Markdown.

Type the following code into your *scratch* buffer:

(defun emphasize (text)
  "Wrap TEXT in asterisks for emphasis."
  (concat "*" text "*"))

Let's analyze this:

• We're defining a function named emphasize.
• It takes one argument, text.
• It has a concise docstring explaining its purpose and referencing the TEXT argument.
• Its body consists of a single expression: a call to the concat function, which joins strings together.

Now, let's bring it to life:

1. Place your cursor just after the final closing parenthesis of the defun expression.
2. Press C-x C-e. You should see emphasize appear in the echo area at the bottom of your screen. This confirms that Emacs has evaluated the definition and now knows about your new function.

To use it, type the following expression into your *scratch* buffer and evaluate it with C-x C-e:

(emphasize "very important")

The result, "*very important*", should appear in the echo area. This result is the return value of the function. Because the concat expression was the last (and only) expression in the function's body, its result became the function's result.

5. Solidifying Your Understanding

To reinforce these concepts, let's turn to the official "An Introduction to Programming in Emacs Lisp". It provides a definitive and formal explanation of function definitions.

Conclusion

In this lesson, you've taken a significant step from using Elisp to actively creating with it. You now have the tools to encapsulate logic and behavior into reusable, documented units.

Key Takeaways:

• Functions are defined using the defun macro.
• A function definition consists of a name, an argument list, an optional docstring, and a body of expressions.
• The value of the last expression in the body becomes the function's return value.
• Docstrings are critical for creating understandable and maintainable code. They power Emacs's built-in help system.
• You can view a function's documentation with C-h f (describe-function).

Preview of the Next Lesson

We have successfully defined a function and called it from our *scratch* buffer. In the next lesson, "Call functions and pass arguments to them," we will explore this process in more depth. Following that, we will learn how to make your functions truly part of Emacs by turning them into interactive commands that you can run with M-x and eventually bind to your own custom keybindings. This will bring you even closer to your goal of tailoring Emacs to your unique workflow.