Change doc-string comments to `new style' [w/`doc:' keyword].

11 files changed, 1009 insertions, 1018 deletions

diff --git a/src/abbrev.c b/src/abbrev.c
index b36613ddd91..723ec1ad425 100644
--- a/src/abbrev.c
+++ b/src/abbrev.c
@@ -22,7 +22,7 @@ Boston, MA 02111-1307, USA.  */
 
 #include <config.h>
 #include <stdio.h>
-#define DOC_STRINGS_IN_COMMENTS
+
 #include "lisp.h"
 #include "commands.h"
 #include "buffer.h"
@@ -84,15 +84,15 @@ int last_abbrev_point;
 Lisp_Object Vpre_abbrev_expand_hook, Qpre_abbrev_expand_hook;
 
 DEFUN ("make-abbrev-table", Fmake_abbrev_table, Smake_abbrev_table, 0, 0, 0,
-       /* Create a new, empty abbrev table object.  */
-       ())
+       doc: /* Create a new, empty abbrev table object.  */)
+     ()
 {
   return Fmake_vector (make_number (59), make_number (0));
 }
 
 DEFUN ("clear-abbrev-table", Fclear_abbrev_table, Sclear_abbrev_table, 1, 1, 0,
-       /* Undefine all abbrevs in abbrev table TABLE, leaving it empty.  */
-       (table))
+       doc: /* Undefine all abbrevs in abbrev table TABLE, leaving it empty.  */)
+     (table)
      Lisp_Object table;
 {
   int i, size;
@@ -106,7 +106,7 @@ DEFUN ("clear-abbrev-table", Fclear_abbrev_table, Sclear_abbrev_table, 1, 1, 0,
 }
 
 DEFUN ("define-abbrev", Fdefine_abbrev, Sdefine_abbrev, 3, 5, 0,
-       /* Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.
+       doc: /* Define an abbrev in TABLE named NAME, to expand to EXPANSION and call HOOK.
 NAME must be a string.
 EXPANSION should usually be a string.
 To undefine an abbrev, define it with EXPANSION = nil.
@@ -115,8 +115,8 @@ it is called after EXPANSION is inserted.
 If EXPANSION is not a string, the abbrev is a special one,
  which does not expand in the usual way but only runs HOOK.
 COUNT, if specified, initializes the abbrev's usage-count
-which is incremented each time the abbrev is used.  */
-       (table, name, expansion, hook, count))
+which is incremented each time the abbrev is used.  */)
+     (table, name, expansion, hook, count)
      Lisp_Object table, name, expansion, hook, count;
 {
   Lisp_Object sym, oexp, ohook, tem;
@@ -149,8 +149,8 @@ which is incremented each time the abbrev is used.  */
 
 DEFUN ("define-global-abbrev", Fdefine_global_abbrev, Sdefine_global_abbrev, 2, 2,
        "sDefine global abbrev: \nsExpansion for %s: ",
-       /* Define ABBREV as a global abbreviation for EXPANSION.  */
-       (abbrev, expansion))
+       doc: /* Define ABBREV as a global abbreviation for EXPANSION.  */)
+     (abbrev, expansion)
      Lisp_Object abbrev, expansion;
 {
   Fdefine_abbrev (Vglobal_abbrev_table, Fdowncase (abbrev),
@@ -160,8 +160,8 @@ DEFUN ("define-global-abbrev", Fdefine_global_abbrev, Sdefine_global_abbrev, 2,
 
 DEFUN ("define-mode-abbrev", Fdefine_mode_abbrev, Sdefine_mode_abbrev, 2, 2,
        "sDefine mode abbrev: \nsExpansion for %s: ",
-       /* Define ABBREV as a mode-specific abbreviation for EXPANSION.  */
-       (abbrev, expansion))
+       doc: /* Define ABBREV as a mode-specific abbreviation for EXPANSION.  */)
+     (abbrev, expansion)
      Lisp_Object abbrev, expansion;
 {
   if (NILP (current_buffer->abbrev_table))
@@ -173,13 +173,13 @@ DEFUN ("define-mode-abbrev", Fdefine_mode_abbrev, Sdefine_mode_abbrev, 2, 2,
 }
 
 DEFUN ("abbrev-symbol", Fabbrev_symbol, Sabbrev_symbol, 1, 2, 0,
-       /* Return the symbol representing abbrev named ABBREV.
+       doc: /* Return the symbol representing abbrev named ABBREV.
 This symbol's name is ABBREV, but it is not the canonical symbol of that name;
 it is interned in an abbrev-table rather than the normal obarray.
 The value is nil if that abbrev is not defined.
 Optional second arg TABLE is abbrev table to look it up in.
-The default is to try buffer's mode-specific abbrev table, then global table.  */
-       (abbrev, table))
+The default is to try buffer's mode-specific abbrev table, then global table.  */)
+     (abbrev, table)
      Lisp_Object abbrev, table;
 {
   Lisp_Object sym;
@@ -202,10 +202,10 @@ The default is to try buffer's mode-specific abbrev table, then global table.  *
 }
 
 DEFUN ("abbrev-expansion", Fabbrev_expansion, Sabbrev_expansion, 1, 2, 0,
-       /* Return the string that ABBREV expands into in the current buffer.
+       doc: /* Return the string that ABBREV expands into in the current buffer.
 Optionally specify an abbrev table as second arg;
-then ABBREV is looked up in that table only.  */
-       (abbrev, table))
+then ABBREV is looked up in that table only.  */)
+     (abbrev, table)
      Lisp_Object abbrev, table;
 {
   Lisp_Object sym;
@@ -218,10 +218,10 @@ then ABBREV is looked up in that table only.  */
   Returns 1 if an expansion is done. */
 
 DEFUN ("expand-abbrev", Fexpand_abbrev, Sexpand_abbrev, 0, 0, "",
-       /* Expand the abbrev before point, if there is an abbrev there.
+       doc: /* Expand the abbrev before point, if there is an abbrev there.
 Effective when explicitly called even when `abbrev-mode' is nil.
-Returns the abbrev symbol, if expansion took place.  */
-       ())
+Returns the abbrev symbol, if expansion took place.  */)
+     ()
 {
   register char *buffer, *p;
   int wordstart, wordend;
@@ -389,10 +389,10 @@ Returns the abbrev symbol, if expansion took place.  */
 }
 
 DEFUN ("unexpand-abbrev", Funexpand_abbrev, Sunexpand_abbrev, 0, 0, "",
-       /* Undo the expansion of the last abbrev that expanded.
+       doc: /* Undo the expansion of the last abbrev that expanded.
 This differs from ordinary undo in that other editing done since then
-is not undone.  */
-       ())
+is not undone.  */)
+     ()
 {
   int opoint = PT;
   int adjust = 0;
@@ -467,13 +467,13 @@ describe_abbrev (sym, stream)
 
 DEFUN ("insert-abbrev-table-description", Finsert_abbrev_table_description,
   Sinsert_abbrev_table_description, 1, 2, 0,
-       /* Insert before point a full description of abbrev table named NAME.
+       doc: /* Insert before point a full description of abbrev table named NAME.
 NAME is a symbol whose value is an abbrev table.
 If optional 2nd arg READABLE is non-nil, a human-readable description
 is inserted.  Otherwise the description is an expression,
 a call to `define-abbrev-table', which would
-define the abbrev table NAME exactly as it is currently defined.  */
-       (name, readable))
+define the abbrev table NAME exactly as it is currently defined.  */)
+     (name, readable)
      Lisp_Object name, readable;
 {
   Lisp_Object table;
@@ -507,10 +507,10 @@ define the abbrev table NAME exactly as it is currently defined.  */
 
 DEFUN ("define-abbrev-table", Fdefine_abbrev_table, Sdefine_abbrev_table,
        2, 2, 0,
-       /* Define TABLENAME (a symbol) as an abbrev table name.
+       doc: /* Define TABLENAME (a symbol) as an abbrev table name.
 Define abbrevs in it according to DEFINITIONS, which is a list of elements
-of the form (ABBREVNAME EXPANSION HOOK USECOUNT).  */
-       (tablename, definitions))
+of the form (ABBREVNAME EXPANSION HOOK USECOUNT).  */)
+     (tablename, definitions)
      Lisp_Object tablename, definitions;
 {
   Lisp_Object name, exp, hook, count;
@@ -541,64 +541,64 @@ of the form (ABBREVNAME EXPANSION HOOK USECOUNT).  */
 void
 syms_of_abbrev ()
 {
-  DEFVAR_LISP ("abbrev-table-name-list", &Vabbrev_table_name_list
-               /* List of symbols whose values are abbrev tables.  */);
+  DEFVAR_LISP ("abbrev-table-name-list", &Vabbrev_table_name_list,
+               doc: /* List of symbols whose values are abbrev tables.  */);
   Vabbrev_table_name_list = Fcons (intern ("fundamental-mode-abbrev-table"),
                                    Fcons (intern ("global-abbrev-table"),
                                           Qnil));
 
-  DEFVAR_LISP ("global-abbrev-table", &Vglobal_abbrev_table
-               /* The abbrev table whose abbrevs affect all buffers.
+  DEFVAR_LISP ("global-abbrev-table", &Vglobal_abbrev_table,
+               doc: /* The abbrev table whose abbrevs affect all buffers.
 Each buffer may also have a local abbrev table.
 If it does, the local table overrides the global one
 for any particular abbrev defined in both.  */);
   Vglobal_abbrev_table = Fmake_abbrev_table ();
 
-  DEFVAR_LISP ("fundamental-mode-abbrev-table", &Vfundamental_mode_abbrev_table
-               /* The abbrev table of mode-specific abbrevs for Fundamental Mode.  */);
+  DEFVAR_LISP ("fundamental-mode-abbrev-table", &Vfundamental_mode_abbrev_table,
+               doc: /* The abbrev table of mode-specific abbrevs for Fundamental Mode.  */);
   Vfundamental_mode_abbrev_table = Fmake_abbrev_table ();
   current_buffer->abbrev_table = Vfundamental_mode_abbrev_table;
   buffer_defaults.abbrev_table = Vfundamental_mode_abbrev_table;
 
-  DEFVAR_LISP ("last-abbrev", &Vlast_abbrev
-               /* The abbrev-symbol of the last abbrev expanded.  See `abbrev-symbol'.  */);
+  DEFVAR_LISP ("last-abbrev", &Vlast_abbrev,
+               doc: /* The abbrev-symbol of the last abbrev expanded.  See `abbrev-symbol'.  */);
 
-  DEFVAR_LISP ("last-abbrev-text", &Vlast_abbrev_text
-               /* The exact text of the last abbrev expanded.
+  DEFVAR_LISP ("last-abbrev-text", &Vlast_abbrev_text,
+               doc: /* The exact text of the last abbrev expanded.
 nil if the abbrev has already been unexpanded.  */);
 
-  DEFVAR_INT ("last-abbrev-location", &last_abbrev_point
-              /* The location of the start of the last abbrev expanded.  */);
+  DEFVAR_INT ("last-abbrev-location", &last_abbrev_point,
+              doc: /* The location of the start of the last abbrev expanded.  */);
 
   Vlast_abbrev = Qnil;
   Vlast_abbrev_text = Qnil;
   last_abbrev_point = 0;
 
-  DEFVAR_LISP ("abbrev-start-location", &Vabbrev_start_location
-               /* Buffer position for `expand-abbrev' to use as the start of the abbrev.
+  DEFVAR_LISP ("abbrev-start-location", &Vabbrev_start_location,
+               doc: /* Buffer position for `expand-abbrev' to use as the start of the abbrev.
 nil means use the word before point as the abbrev.
 Calling `expand-abbrev' sets this to nil.  */);
   Vabbrev_start_location = Qnil;
 
-  DEFVAR_LISP ("abbrev-start-location-buffer", &Vabbrev_start_location_buffer
-               /* Buffer that `abbrev-start-location' has been set for.
+  DEFVAR_LISP ("abbrev-start-location-buffer", &Vabbrev_start_location_buffer,
+               doc: /* Buffer that `abbrev-start-location' has been set for.
 Trying to expand an abbrev in any other buffer clears `abbrev-start-location'.  */);
   Vabbrev_start_location_buffer = Qnil;
 
-  DEFVAR_PER_BUFFER ("local-abbrev-table", &current_buffer->abbrev_table, Qnil
-                     /* Local (mode-specific) abbrev table of current buffer.  */);
+  DEFVAR_PER_BUFFER ("local-abbrev-table", &current_buffer->abbrev_table, Qnil,
+                     doc: /* Local (mode-specific) abbrev table of current buffer.  */);
 
-  DEFVAR_BOOL ("abbrevs-changed", &abbrevs_changed
-               /* Set non-nil by defining or altering any word abbrevs.
+  DEFVAR_BOOL ("abbrevs-changed", &abbrevs_changed,
+               doc: /* Set non-nil by defining or altering any word abbrevs.
 This causes `save-some-buffers' to offer to save the abbrevs.  */);
   abbrevs_changed = 0;
 
-  DEFVAR_BOOL ("abbrev-all-caps", &abbrev_all_caps
-               /* *Set non-nil means expand multi-word abbrevs all caps if abbrev was so.  */);
+  DEFVAR_BOOL ("abbrev-all-caps", &abbrev_all_caps,
+               doc: /* *Set non-nil means expand multi-word abbrevs all caps if abbrev was so.  */);
   abbrev_all_caps = 0;
 
-  DEFVAR_LISP ("pre-abbrev-expand-hook", &Vpre_abbrev_expand_hook
-               /* Function or functions to be called before abbrev expansion is done.
+  DEFVAR_LISP ("pre-abbrev-expand-hook", &Vpre_abbrev_expand_hook,
+               doc: /* Function or functions to be called before abbrev expansion is done.
 This is the first thing that `expand-abbrev' does, and so this may change
 the current abbrev table before abbrev lookup happens.  */);
   Vpre_abbrev_expand_hook = Qnil;
diff --git a/src/alloc.c b/src/alloc.c
index a7780e9ad91..101f599d009 100644
--- a/src/alloc.c
+++ b/src/alloc.c
@@ -38,7 +38,6 @@ Boston, MA 02111-1307, USA.  */
    replaced, this file likely will not be used.  */
 
 #undef HIDE_LISP_IMPLEMENTATION
-#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "process.h"
 #include "intervals.h"
@@ -1660,9 +1659,9 @@ compact_small_strings ()
 
 
 DEFUN ("make-string", Fmake_string, Smake_string, 2, 2, 0,
-  /* Return a newly created string of length LENGTH, with each element being INIT.
-Both LENGTH and INIT must be numbers.  */
-       (length, init))
+  doc: /* Return a newly created string of length LENGTH, with each element being INIT.
+Both LENGTH and INIT must be numbers.  */)
+     (length, init)
      Lisp_Object length, init;
 {
   register Lisp_Object val;
@@ -1704,9 +1703,9 @@ Both LENGTH and INIT must be numbers.  */
 
 
 DEFUN ("make-bool-vector", Fmake_bool_vector, Smake_bool_vector, 2, 2, 0,
-  /* Return a new bool-vector of length LENGTH, using INIT for as each element.
-LENGTH must be a number.  INIT matters only in whether it is t or nil.  */
-       (length, init))
+  doc: /* Return a new bool-vector of length LENGTH, using INIT for as each element.
+LENGTH must be a number.  INIT matters only in whether it is t or nil.  */)
+     (length, init)
      Lisp_Object length, init;
 {
   register Lisp_Object val;
@@ -2058,8 +2057,8 @@ free_cons (ptr)
 
 
 DEFUN ("cons", Fcons, Scons, 2, 2, 0,
-  /* Create a new cons, give it CAR and CDR as components, and return it.  */
-       (car, cdr))
+  doc: /* Create a new cons, give it CAR and CDR as components, and return it.  */)
+     (car, cdr)
      Lisp_Object car, cdr;
 {
   register Lisp_Object val;
@@ -2131,9 +2130,9 @@ list5 (arg1, arg2, arg3, arg4, arg5)
 
 
 DEFUN ("list", Flist, Slist, 0, MANY, 0,
-  /* Return a newly created list with specified arguments as elements.
-Any number of arguments, even zero arguments, are allowed.  */
-       (nargs, args))
+  doc: /* Return a newly created list with specified arguments as elements.
+Any number of arguments, even zero arguments, are allowed.  */)
+     (nargs, args)
      int nargs;
      register Lisp_Object *args;
 {
@@ -2150,8 +2149,8 @@ Any number of arguments, even zero arguments, are allowed.  */
 
 
 DEFUN ("make-list", Fmake_list, Smake_list, 2, 2, 0,
-  /* Return a newly created list of length LENGTH, with each element being INIT.  */
-       (length, init))
+  doc: /* Return a newly created list of length LENGTH, with each element being INIT.  */)
+     (length, init)
      register Lisp_Object length, init;
 {
   register Lisp_Object val;
@@ -2337,9 +2336,9 @@ allocate_other_vector (len)
 
 
 DEFUN ("make-vector", Fmake_vector, Smake_vector, 2, 2, 0,
-  /* Return a newly created vector of length LENGTH, with each element being INIT.
-See also the function `vector'.  */
-       (length, init))
+  doc: /* Return a newly created vector of length LENGTH, with each element being INIT.
+See also the function `vector'.  */)
+     (length, init)
      register Lisp_Object length, init;
 {
   Lisp_Object vector;
@@ -2360,11 +2359,11 @@ See also the function `vector'.  */
 
 
 DEFUN ("make-char-table", Fmake_char_table, Smake_char_table, 1, 2, 0,
-  /* Return a newly created char-table, with purpose PURPOSE.
+  doc: /* Return a newly created char-table, with purpose PURPOSE.
 Each element is initialized to INIT, which defaults to nil.
 PURPOSE should be a symbol which has a `char-table-extra-slots' property.
-The property's value should be an integer between 0 and 10.  */
-       (purpose, init))
+The property's value should be an integer between 0 and 10.  */)
+     (purpose, init)
      register Lisp_Object purpose, init;
 {
   Lisp_Object vector;
@@ -2403,9 +2402,9 @@ make_sub_char_table (defalt)
 
 
 DEFUN ("vector", Fvector, Svector, 0, MANY, 0,
-  /* Return a newly created vector with specified arguments as elements.
-Any number of arguments, even zero arguments, are allowed.  */
-       (nargs, args))
+  doc: /* Return a newly created vector with specified arguments as elements.
+Any number of arguments, even zero arguments, are allowed.  */)
+     (nargs, args)
      register int nargs;
      Lisp_Object *args;
 {
@@ -2423,12 +2422,12 @@ Any number of arguments, even zero arguments, are allowed.  */
 
 
 DEFUN ("make-byte-code", Fmake_byte_code, Smake_byte_code, 4, MANY, 0,
-  /* Create a byte-code object with specified arguments as elements.
+  doc: /* Create a byte-code object with specified arguments as elements.
 The arguments should be the arglist, bytecode-string, constant vector,
 stack size, (optional) doc string, and (optional) interactive spec.
 The first four arguments are required; at most six have any
-significance.  */
-       (nargs, args))
+significance.  */)
+     (nargs, args)
      register int nargs;
      Lisp_Object *args;
 {
@@ -2511,9 +2510,9 @@ init_symbol ()
 
 
 DEFUN ("make-symbol", Fmake_symbol, Smake_symbol, 1, 1, 0,
-  /* Return a newly allocated uninterned symbol whose name is NAME.
-Its value and function definition are void, and its property list is nil.  */
-       (name))
+  doc: /* Return a newly allocated uninterned symbol whose name is NAME.
+Its value and function definition are void, and its property list is nil.  */)
+     (name)
      Lisp_Object name;
 {
   register Lisp_Object val;
@@ -2629,8 +2628,8 @@ allocate_misc ()
 }
 
 DEFUN ("make-marker", Fmake_marker, Smake_marker, 0, 0, 0,
-  /* Return a newly allocated marker which does not point at any place.  */
-       ())
+  doc: /* Return a newly allocated marker which does not point at any place.  */)
+     ()
 {
   register Lisp_Object val;
   register struct Lisp_Marker *p;
@@ -3300,8 +3299,8 @@ static int max_live, max_zombies;
 static double avg_live;
 
 DEFUN ("gc-status", Fgc_status, Sgc_status, 0, 0, "",
-       /* Show information about live and zombie objects.  */
-       ())
+       doc: /* Show information about live and zombie objects.  */)
+     ()
 {
   Lisp_Object args[7];
   args[0] = build_string ("%d GCs, avg live/zombies = %.2f/%.2f (%f%%), max %d/%d");
@@ -3540,7 +3539,7 @@ mark_memory (start, end)
      only a pointer to them remains.  Example:
 
      DEFUN ("testme", Ftestme, Stestme, 0, 0, 0, "")
-          ()
+     ()
      {
        Lisp_Object obj = build_string ("test");
        struct Lisp_String *s = XSTRING (obj);
@@ -3919,10 +3918,10 @@ make_pure_vector (len)
 
 
 DEFUN ("purecopy", Fpurecopy, Spurecopy, 1, 1, 0,
-       /* Make a copy of OBJECT in pure storage.
+       doc: /* Make a copy of OBJECT in pure storage.
 Recursively copies contents of vectors and cons cells.
-Does not copy symbols.  Copies strings without text properties.  */
-       (obj))
+Does not copy symbols.  Copies strings without text properties.  */)
+     (obj)
      register Lisp_Object obj;
 {
   if (NILP (Vpurify_flag))
@@ -4016,15 +4015,15 @@ inhibit_garbage_collection ()
 
 
 DEFUN ("garbage-collect", Fgarbage_collect, Sgarbage_collect, 0, 0, "",
-       /* Reclaim storage for Lisp objects no longer needed.
+       doc: /* Reclaim storage for Lisp objects no longer needed.
 Returns info on amount of space in use:
  ((USED-CONSES . FREE-CONSES) (USED-SYMS . FREE-SYMS)
   (USED-MARKERS . FREE-MARKERS) USED-STRING-CHARS USED-VECTOR-SLOTS
   (USED-FLOATS . FREE-FLOATS) (USED-INTERVALS . FREE-INTERVALS)
   (USED-STRINGS . FREE-STRINGS))
 Garbage collection happens automatically if you cons more than
-`gc-cons-threshold' bytes of Lisp data since previous garbage collection.  */
-       ())
+`gc-cons-threshold' bytes of Lisp data since previous garbage collection.  */)
+     ()
 {
   register struct gcpro *tail;
   register struct specbinding *bind;
@@ -5321,10 +5320,10 @@ gc_sweep ()
 /* Debugging aids.  */
 
 DEFUN ("memory-limit", Fmemory_limit, Smemory_limit, 0, 0, 0,
-  /* Return the address of the last byte Emacs has allocated, divided by 1024.
+  doc: /* Return the address of the last byte Emacs has allocated, divided by 1024.
 This may be helpful in debugging Emacs's memory usage.
-We divide the value by 1024 to make sure it fits in a Lisp integer.  */
-       ())
+We divide the value by 1024 to make sure it fits in a Lisp integer.  */)
+     ()
 {
   Lisp_Object end;
 
@@ -5334,7 +5333,7 @@ We divide the value by 1024 to make sure it fits in a Lisp integer.  */
 }
 
 DEFUN ("memory-use-counts", Fmemory_use_counts, Smemory_use_counts, 0, 0, 0,
-  /* Return a list of counters that measure how much consing there has been.
+  doc: /* Return a list of counters that measure how much consing there has been.
 Each of these counters increments for a certain kind of object.
 The counters wrap around from the largest positive integer to zero.
 Garbage collection does not decrease them.
@@ -5345,8 +5344,8 @@ except for VECTOR-CELLS and STRING-CHARS, which count the total length of
 objects consed.
 MISCS include overlays, markers, and some internal types.
 Frames, windows, buffers, and subprocesses count as vectors
-  (but the contents of a buffer's text do not count here).  */
-       ())
+  (but the contents of a buffer's text do not count here).  */)
+     ()
 {
   Lisp_Object consed[8];
 
@@ -5439,8 +5438,8 @@ init_alloc ()
 void
 syms_of_alloc ()
 {
-  DEFVAR_INT ("gc-cons-threshold", &gc_cons_threshold
-    /* *Number of bytes of consing between garbage collections.
+  DEFVAR_INT ("gc-cons-threshold", &gc_cons_threshold,
+    doc: /* *Number of bytes of consing between garbage collections.
 Garbage collection can happen automatically once this many bytes have been
 allocated since the last garbage collection.  All data types count.
 
@@ -5449,58 +5448,58 @@ Garbage collection happens automatically only when `eval' is called.
 By binding this temporarily to a large number, you can effectively
 prevent garbage collection during a part of the program.  */);
 
-  DEFVAR_INT ("pure-bytes-used", &pure_bytes_used
-    /* Number of bytes of sharable Lisp data allocated so far.  */);
+  DEFVAR_INT ("pure-bytes-used", &pure_bytes_used,
+    doc: /* Number of bytes of sharable Lisp data allocated so far.  */);
 
-  DEFVAR_INT ("cons-cells-consed", &cons_cells_consed
-    /* Number of cons cells that have been consed so far.  */);
+  DEFVAR_INT ("cons-cells-consed", &cons_cells_consed,
+    doc: /* Number of cons cells that have been consed so far.  */);
 
-  DEFVAR_INT ("floats-consed", &floats_consed
-    /* Number of floats that have been consed so far.  */);
+  DEFVAR_INT ("floats-consed", &floats_consed,
+    doc: /* Number of floats that have been consed so far.  */);
 
-  DEFVAR_INT ("vector-cells-consed", &vector_cells_consed
-    /* Number of vector cells that have been consed so far.  */);
+  DEFVAR_INT ("vector-cells-consed", &vector_cells_consed,
+    doc: /* Number of vector cells that have been consed so far.  */);
 
-  DEFVAR_INT ("symbols-consed", &symbols_consed
-    /* Number of symbols that have been consed so far.  */);
+  DEFVAR_INT ("symbols-consed", &symbols_consed,
+    doc: /* Number of symbols that have been consed so far.  */);
 
-  DEFVAR_INT ("string-chars-consed", &string_chars_consed
-    /* Number of string characters that have been consed so far.  */);
+  DEFVAR_INT ("string-chars-consed", &string_chars_consed,
+    doc: /* Number of string characters that have been consed so far.  */);
 
-  DEFVAR_INT ("misc-objects-consed", &misc_objects_consed
-    /* Number of miscellaneous objects that have been consed so far.  */);
+  DEFVAR_INT ("misc-objects-consed", &misc_objects_consed,
+    doc: /* Number of miscellaneous objects that have been consed so far.  */);
 
-  DEFVAR_INT ("intervals-consed", &intervals_consed
-    /* Number of intervals that have been consed so far.  */);
+  DEFVAR_INT ("intervals-consed", &intervals_consed,
+    doc: /* Number of intervals that have been consed so far.  */);
 
-  DEFVAR_INT ("strings-consed", &strings_consed
-    /* Number of strings that have been consed so far.  */);
+  DEFVAR_INT ("strings-consed", &strings_consed,
+    doc: /* Number of strings that have been consed so far.  */);
 
-  DEFVAR_LISP ("purify-flag", &Vpurify_flag
-    /* Non-nil means loading Lisp code in order to dump an executable.
+  DEFVAR_LISP ("purify-flag", &Vpurify_flag,
+    doc: /* Non-nil means loading Lisp code in order to dump an executable.
 This means that certain objects should be allocated in shared (pure) space.  */);
 
-  DEFVAR_INT ("undo-limit", &undo_limit
-    /* Keep no more undo information once it exceeds this size.
+  DEFVAR_INT ("undo-limit", &undo_limit,
+    doc: /* Keep no more undo information once it exceeds this size.
 This limit is applied when garbage collection happens.
 The size is counted as the number of bytes occupied,
 which includes both saved text and other data.  */);
   undo_limit = 20000;
 
-  DEFVAR_INT ("undo-strong-limit", &undo_strong_limit
-    /* Don't keep more than this much size of undo information.
+  DEFVAR_INT ("undo-strong-limit", &undo_strong_limit,
+    doc: /* Don't keep more than this much size of undo information.
 A command which pushes past this size is itself forgotten.
 This limit is applied when garbage collection happens.
 The size is counted as the number of bytes occupied,
 which includes both saved text and other data.  */);
   undo_strong_limit = 30000;
 
-  DEFVAR_BOOL ("garbage-collection-messages", &garbage_collection_messages
-    /* Non-nil means display messages at start and end of garbage collection.  */);
+  DEFVAR_BOOL ("garbage-collection-messages", &garbage_collection_messages,
+    doc: /* Non-nil means display messages at start and end of garbage collection.  */);
   garbage_collection_messages = 0;
 
-  DEFVAR_LISP ("post-gc-hook", &Vpost_gc_hook
-    /* Hook run after garbage collection has finished.  */);
+  DEFVAR_LISP ("post-gc-hook", &Vpost_gc_hook,
+    doc: /* Hook run after garbage collection has finished.  */);
   Vpost_gc_hook = Qnil;
   Qpost_gc_hook = intern ("post-gc-hook");
   staticpro (&Qpost_gc_hook);
diff --git a/src/buffer.c b/src/buffer.c
index 2bb785bda99..7cbd0b68246 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -39,7 +39,7 @@ extern int errno;
 #ifdef HAVE_UNISTD_H
 #include <unistd.h>
 #endif
-#define DOC_STRINGS_IN_COMMENTS
+
 #include "lisp.h"
 #include "intervals.h"
 #include "window.h"
@@ -198,9 +198,9 @@ nsberror (spec)
 }
 
 DEFUN ("buffer-live-p", Fbuffer_live_p, Sbuffer_live_p, 1, 1, 0,
-       /* Return non-nil if OBJECT is a buffer which has not been killed.
-Value is nil if OBJECT is not a buffer or if it has been killed.  */
-       (object))
+       doc: /* Return non-nil if OBJECT is a buffer which has not been killed.
+Value is nil if OBJECT is not a buffer or if it has been killed.  */)
+     (object)
      Lisp_Object object;
 {
   return ((BUFFERP (object) && ! NILP (XBUFFER (object)->name))
@@ -208,9 +208,9 @@ Value is nil if OBJECT is not a buffer or if it has been killed.  */
 }
 
 DEFUN ("buffer-list", Fbuffer_list, Sbuffer_list, 0, 1, 0,
-       /* Return a list of all existing live buffers.
-If the optional arg FRAME is a frame, we return that frame's buffer list.  */
-       (frame))
+       doc: /* Return a list of all existing live buffers.
+If the optional arg FRAME is a frame, we return that frame's buffer list.  */)
+     (frame)
      Lisp_Object frame;
 {
   Lisp_Object framelist, general;
@@ -259,10 +259,10 @@ assoc_ignore_text_properties (key, list)
 }
 
 DEFUN ("get-buffer", Fget_buffer, Sget_buffer, 1, 1, 0,
-       /* Return the buffer named NAME (a string).
+       doc: /* Return the buffer named NAME (a string).
 If there is no live buffer named NAME, return nil.
-NAME may also be a buffer; if so, the value is that buffer.  */
-       (name))
+NAME may also be a buffer; if so, the value is that buffer.  */)
+     (name)
      register Lisp_Object name;
 {
   if (BUFFERP (name))
@@ -273,11 +273,11 @@ NAME may also be a buffer; if so, the value is that buffer.  */
 }
 
 DEFUN ("get-file-buffer", Fget_file_buffer, Sget_file_buffer, 1, 1, 0,
-       /* Return the buffer visiting file FILENAME (a string).
+       doc: /* Return the buffer visiting file FILENAME (a string).
 The buffer's `buffer-file-name' must match exactly the expansion of FILENAME.
 If there is no such live buffer, return nil.
-See also `find-buffer-visiting'.  */
-       (filename))
+See also `find-buffer-visiting'.  */)
+     (filename)
      register Lisp_Object filename;
 {
   register Lisp_Object tail, buf, tem;
@@ -326,12 +326,12 @@ get_truename_buffer (filename)
 int buffer_count;
 
 DEFUN ("get-buffer-create", Fget_buffer_create, Sget_buffer_create, 1, 1, 0,
-       /* Return the buffer named NAME, or create such a buffer and return it.
+       doc: /* Return the buffer named NAME, or create such a buffer and return it.
 A new buffer is created if there is no live buffer named NAME.
 If NAME starts with a space, the new buffer does not keep undo information.
 If NAME is a buffer instead of a string, then it is the value returned.
-The value is never nil.  */
-       (name))
+The value is never nil.  */)
+     (name)
      register Lisp_Object name;
 {
   register Lisp_Object buf;
@@ -506,13 +506,13 @@ clone_per_buffer_values (from, to)
 DEFUN ("make-indirect-buffer", Fmake_indirect_buffer, Smake_indirect_buffer,
        2, 3,
        "bMake indirect buffer (to buffer): \nBName of indirect buffer: ",
-       /* Create and return an indirect buffer for buffer BASE-BUFFER, named NAME.
+       doc: /* Create and return an indirect buffer for buffer BASE-BUFFER, named NAME.
 BASE-BUFFER should be an existing buffer (or buffer name).
 NAME should be a string which is not the name of an existing buffer.
 Optional argument CLONE non-nil means preserve BASE-BUFFER's state,
 such as major and minor modes, in the indirect buffer.
-CLONE nil means the indirect buffer's state is reset to default values.  */
-       (base_buffer, name, clone))
+CLONE nil means the indirect buffer's state is reset to default values.  */)
+     (base_buffer, name, clone)
      Lisp_Object base_buffer, name, clone;
 {
   Lisp_Object buf;
@@ -725,14 +725,14 @@ reset_buffer_local_variables (b, permanent_too)
 
 DEFUN ("generate-new-buffer-name", Fgenerate_new_buffer_name, Sgenerate_new_buffer_name,
   1, 2, 0,
-       /* Return a string that is the name of no existing buffer based on NAME.
+       doc: /* Return a string that is the name of no existing buffer based on NAME.
 If there is no live buffer named NAME, then return NAME.
 Otherwise modify name by appending `<NUMBER>', incrementing NUMBER
 until an unused name is found, and then return that name.
 Optional second argument IGNORE specifies a name that is okay to use
 \(if it is in the sequence to be tried)
-even if a buffer with that name exists.  */
-       (name, ignore))
+even if a buffer with that name exists.  */)
+     (name, ignore)
      register Lisp_Object name, ignore;
 {
   register Lisp_Object gentemp, tem;
@@ -761,9 +761,9 @@ even if a buffer with that name exists.  */
 
 
 DEFUN ("buffer-name", Fbuffer_name, Sbuffer_name, 0, 1, 0,
-       /* Return the name of BUFFER, as a string.
-With no argument or nil as argument, return the name of the current buffer.  */
-       (buffer))
+       doc: /* Return the name of BUFFER, as a string.
+With no argument or nil as argument, return the name of the current buffer.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   if (NILP (buffer))
@@ -773,9 +773,9 @@ With no argument or nil as argument, return the name of the current buffer.  */
 }
 
 DEFUN ("buffer-file-name", Fbuffer_file_name, Sbuffer_file_name, 0, 1, 0,
-       /* Return name of file BUFFER is visiting, or nil if none.
-No argument or nil as argument means use the current buffer.  */
-       (buffer))
+       doc: /* Return name of file BUFFER is visiting, or nil if none.
+No argument or nil as argument means use the current buffer.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   if (NILP (buffer))
@@ -786,9 +786,9 @@ No argument or nil as argument means use the current buffer.  */
 
 DEFUN ("buffer-base-buffer", Fbuffer_base_buffer, Sbuffer_base_buffer,
        0, 1, 0,
-       /* Return the base buffer of indirect buffer BUFFER.
-If BUFFER is not indirect, return nil.  */
-       (buffer))
+       doc: /* Return the base buffer of indirect buffer BUFFER.
+If BUFFER is not indirect, return nil.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   struct buffer *base;
@@ -810,12 +810,12 @@ If BUFFER is not indirect, return nil.  */
 
 DEFUN ("buffer-local-variables", Fbuffer_local_variables,
   Sbuffer_local_variables, 0, 1, 0,
-       /* Return an alist of variables that are buffer-local in BUFFER.
+       doc: /* Return an alist of variables that are buffer-local in BUFFER.
 Most elements look like (SYMBOL . VALUE), describing one variable.
 For a symbol that is locally unbound, just the symbol appears in the value.
 Note that storing new VALUEs in these elements doesn't change the variables.
-No argument or nil as argument means use current buffer as BUFFER.  */
-       (buffer))
+No argument or nil as argument means use current buffer as BUFFER.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   register struct buffer *buf;
@@ -882,9 +882,9 @@ No argument or nil as argument means use current buffer as BUFFER.  */
 
 DEFUN ("buffer-modified-p", Fbuffer_modified_p, Sbuffer_modified_p,
   0, 1, 0,
-       /* Return t if BUFFER was modified since its file was last read or saved.
-No argument or nil as argument means use current buffer as BUFFER.  */
-       (buffer))
+       doc: /* Return t if BUFFER was modified since its file was last read or saved.
+No argument or nil as argument means use current buffer as BUFFER.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   register struct buffer *buf;
@@ -901,9 +901,9 @@ No argument or nil as argument means use current buffer as BUFFER.  */
 
 DEFUN ("set-buffer-modified-p", Fset_buffer_modified_p, Sset_buffer_modified_p,
   1, 1, 0,
-       /* Mark current buffer as modified or unmodified according to FLAG.
-A non-nil FLAG means mark the buffer modified.  */
-       (flag))
+       doc: /* Mark current buffer as modified or unmodified according to FLAG.
+A non-nil FLAG means mark the buffer modified.  */)
+     (flag)
      register Lisp_Object flag;
 {
   register int already;
@@ -952,10 +952,10 @@ A non-nil FLAG means mark the buffer modified.  */
 
 DEFUN ("restore-buffer-modified-p", Frestore_buffer_modified_p,
        Srestore_buffer_modified_p, 1, 1, 0,
-       /* Like `set-buffer-modified-p', with a differences concerning redisplay.
+       doc: /* Like `set-buffer-modified-p', with a differences concerning redisplay.
 It is not ensured that mode lines will be updated to show the modified
-state of the current buffer.  Use with care.  */
-       (flag))
+state of the current buffer.  Use with care.  */)
+     (flag)
      Lisp_Object flag;
 {
 #ifdef CLASH_DETECTION
@@ -982,11 +982,11 @@ state of the current buffer.  Use with care.  */
 
 DEFUN ("buffer-modified-tick", Fbuffer_modified_tick, Sbuffer_modified_tick,
   0, 1, 0,
-       /* Return BUFFER's tick counter, incremented for each change in text.
+       doc: /* Return BUFFER's tick counter, incremented for each change in text.
 Each buffer has a tick counter which is incremented each time the text in
 that buffer is changed.  It wraps around occasionally.
-No argument or nil as argument means use current buffer as BUFFER.  */
-       (buffer))
+No argument or nil as argument means use current buffer as BUFFER.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   register struct buffer *buf;
@@ -1003,15 +1003,15 @@ No argument or nil as argument means use current buffer as BUFFER.  */
 
 DEFUN ("rename-buffer", Frename_buffer, Srename_buffer, 1, 2,
        "sRename buffer (to new name): \nP",
-       /* Change current buffer's name to NEWNAME (a string).
+       doc: /* Change current buffer's name to NEWNAME (a string).
 If second arg UNIQUE is nil or omitted, it is an error if a
 buffer named NEWNAME already exists.
 If UNIQUE is non-nil, come up with a new name using
 `generate-new-buffer-name'.
 Interactively, you can set UNIQUE with a prefix argument.
 We return the name we actually gave the buffer.
-This does not change the name of the visited file (if any).  */
-       (newname, unique))
+This does not change the name of the visited file (if any).  */)
+     (newname, unique)
      register Lisp_Object newname, unique;
 {
   register Lisp_Object tem, buf;
@@ -1052,14 +1052,14 @@ This does not change the name of the visited file (if any).  */
 }
 
 DEFUN ("other-buffer", Fother_buffer, Sother_buffer, 0, 3, 0,
-       /* Return most recently selected buffer other than BUFFER.
+       doc: /* Return most recently selected buffer other than BUFFER.
 Buffers not visible in windows are preferred to visible buffers,
 unless optional second argument VISIBLE-OK is non-nil.
 If the optional third argument FRAME is non-nil, use that frame's
 buffer list instead of the selected frame's buffer list.
 If no other buffer exists, the buffer `*scratch*' is returned.
-If BUFFER is omitted or nil, some interesting buffer is returned.  */
-       (buffer, visible_ok, frame))
+If BUFFER is omitted or nil, some interesting buffer is returned.  */)
+     (buffer, visible_ok, frame)
      register Lisp_Object buffer, visible_ok, frame;
 {
   Lisp_Object Fset_buffer_major_mode ();
@@ -1123,9 +1123,9 @@ If BUFFER is omitted or nil, some interesting buffer is returned.  */
 
 DEFUN ("buffer-disable-undo", Fbuffer_disable_undo, Sbuffer_disable_undo,
        0, 1, "",
-       /* Make BUFFER stop keeping undo information.
-No argument or nil as argument means do this for the current buffer.  */
-       (buffer))
+       doc: /* Make BUFFER stop keeping undo information.
+No argument or nil as argument means do this for the current buffer.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   Lisp_Object real_buffer;
@@ -1146,9 +1146,9 @@ No argument or nil as argument means do this for the current buffer.  */
 
 DEFUN ("buffer-enable-undo", Fbuffer_enable_undo, Sbuffer_enable_undo,
        0, 1, "",
-       /* Start keeping undo information for buffer BUFFER.
-No argument or nil as argument means do this for the current buffer.  */
-       (buffer))
+       doc: /* Start keeping undo information for buffer BUFFER.
+No argument or nil as argument means do this for the current buffer.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   Lisp_Object real_buffer;
@@ -1175,7 +1175,7 @@ The buffer being killed will be current while the hook is running.\n\
 See `kill-buffer'."
  */
 DEFUN ("kill-buffer", Fkill_buffer, Skill_buffer, 1, 1, "bKill buffer: ",
-       /* Kill the buffer BUFFER.
+       doc: /* Kill the buffer BUFFER.
 The argument may be a buffer or may be the name of a buffer.
 An argument of nil means kill the current buffer.
 
@@ -1187,8 +1187,8 @@ before the buffer is actually killed.  The buffer to be killed is current
 when the hook functions are called.
 
 Any processes that have this buffer as the `process-buffer' are killed
-with SIGHUP.  */
-       (buffer))
+with SIGHUP.  */)
+     (buffer)
      Lisp_Object buffer;
 {
   Lisp_Object buf;
@@ -1449,12 +1449,12 @@ record_buffer (buf)
 }
 
 DEFUN ("set-buffer-major-mode", Fset_buffer_major_mode, Sset_buffer_major_mode, 1, 1, 0,
-       /* Set an appropriate major mode for BUFFER.
+       doc: /* Set an appropriate major mode for BUFFER.
 For the *scratch* buffer, use `initial-major-mode', otherwise chose a mode
 according to `default-major-mode'.
 Use this function before selecting the buffer, since it may need to inspect
-the current buffer's major mode.  */
-       (buffer))
+the current buffer's major mode.  */)
+     (buffer)
      Lisp_Object buffer;
 {
   int count;
@@ -1536,15 +1536,15 @@ switch_to_buffer_1 (buffer, norecord)
 }
 
 DEFUN ("switch-to-buffer", Fswitch_to_buffer, Sswitch_to_buffer, 1, 2, "BSwitch to buffer: ",
-       /* Select buffer BUFFER in the current window.
+       doc: /* Select buffer BUFFER in the current window.
 BUFFER may be a buffer or a buffer name.
 Optional second arg NORECORD non-nil means
 do not put this buffer at the front of the list of recently selected ones.
 
 WARNING: This is NOT the way to work on another buffer temporarily
 within a Lisp program!  Use `set-buffer' instead.  That avoids messing with
-the window-buffer correspondences.  */
-       (buffer, norecord))
+the window-buffer correspondences.  */)
+     (buffer, norecord)
      Lisp_Object buffer, norecord;
 {
   char *err;
@@ -1556,7 +1556,7 @@ the window-buffer correspondences.  */
 }
 
 DEFUN ("pop-to-buffer", Fpop_to_buffer, Spop_to_buffer, 1, 3, 0,
-       /* Select buffer BUFFER in some window, preferably a different one.
+       doc: /* Select buffer BUFFER in some window, preferably a different one.
 If BUFFER is nil, then some other buffer is chosen.
 If `pop-up-windows' is non-nil, windows can be split to do this.
 If optional second arg OTHER-WINDOW is non-nil, insist on finding another
@@ -1565,8 +1565,8 @@ This uses the function `display-buffer' as a subroutine; see the documentation
 of `display-buffer' for additional customization information.
 
 Optional third arg NORECORD non-nil means
-do not put this buffer at the front of the list of recently selected ones.  */
-       (buffer, other_window, norecord))
+do not put this buffer at the front of the list of recently selected ones.  */)
+     (buffer, other_window, norecord)
      Lisp_Object buffer, other_window, norecord;
 {
   register Lisp_Object buf;
@@ -1590,8 +1590,8 @@ do not put this buffer at the front of the list of recently selected ones.  */
 }
 
 DEFUN ("current-buffer", Fcurrent_buffer, Scurrent_buffer, 0, 0, 0,
-       /* Return the current buffer as a Lisp object.  */
-       ())
+       doc: /* Return the current buffer as a Lisp object.  */)
+     ()
 {
   register Lisp_Object buf;
   XSETBUFFER (buf, current_buffer);
@@ -1786,13 +1786,13 @@ set_buffer_temp (b)
 }
 
 DEFUN ("set-buffer", Fset_buffer, Sset_buffer, 1, 1, 0,
-       /* Make the buffer BUFFER current for editing operations.
+       doc: /* Make the buffer BUFFER current for editing operations.
 BUFFER may be a buffer or the name of an existing buffer.
 See also `save-excursion' when you want to make a buffer current temporarily.
 This function does not display the buffer, so its effect ends
 when the current command terminates.
-Use `switch-to-buffer' or `pop-to-buffer' to switch buffers permanently.  */
-       (buffer))
+Use `switch-to-buffer' or `pop-to-buffer' to switch buffers permanently.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   register Lisp_Object buf;
@@ -1818,8 +1818,8 @@ set_buffer_if_live (buffer)
 
 DEFUN ("barf-if-buffer-read-only", Fbarf_if_buffer_read_only,
                                    Sbarf_if_buffer_read_only, 0, 0, 0,
-       /* Signal a `buffer-read-only' error if the current buffer is read-only.  */
-       ())
+       doc: /* Signal a `buffer-read-only' error if the current buffer is read-only.  */)
+     ()
 {
   if (!NILP (current_buffer->read_only)
       && NILP (Vinhibit_read_only))
@@ -1828,13 +1828,13 @@ DEFUN ("barf-if-buffer-read-only", Fbarf_if_buffer_read_only,
 }
 
 DEFUN ("bury-buffer", Fbury_buffer, Sbury_buffer, 0, 1, "",
-       /* Put BUFFER at the end of the list of all buffers.
+       doc: /* Put BUFFER at the end of the list of all buffers.
 There it is the least likely candidate for `other-buffer' to return;
 thus, the least likely buffer for \\[switch-to-buffer] to select by default.
 If BUFFER is nil or omitted, bury the current buffer.
 Also, if BUFFER is nil or omitted, remove the current buffer from the
-selected window if it is displayed there.  */
-       (buffer))
+selected window if it is displayed there.  */)
+     (buffer)
      register Lisp_Object buffer;
 {
   /* Figure out what buffer we're going to bury.  */
@@ -1882,10 +1882,10 @@ selected window if it is displayed there.  */
 }
 
 DEFUN ("erase-buffer", Ferase_buffer, Serase_buffer, 0, 0, "*",
-       /* Delete the entire contents of the current buffer.
+       doc: /* Delete the entire contents of the current buffer.
 Any narrowing restriction in effect (see `narrow-to-region') is removed,
-so the buffer is truly empty after this.  */
-       ())
+so the buffer is truly empty after this.  */)
+     ()
 {
   Fwiden ();
 
@@ -1956,12 +1956,12 @@ advance_to_char_boundary (byte_pos)
 
 DEFUN ("set-buffer-multibyte", Fset_buffer_multibyte, Sset_buffer_multibyte,
        1, 1, 0,
-       /* Set the multibyte flag of the current buffer to FLAG.
+       doc: /* Set the multibyte flag of the current buffer to FLAG.
 If FLAG is t, this makes the buffer a multibyte buffer.
 If FLAG is nil, this makes the buffer a single-byte buffer.
 The buffer contents remain unchanged as a sequence of bytes
-but the contents viewed as characters do change.  */
-       (flag))
+but the contents viewed as characters do change.  */)
+     (flag)
      Lisp_Object flag;
 {
   Lisp_Object tail, markers;
@@ -2209,7 +2209,7 @@ but the contents viewed as characters do change.  */
 
 DEFUN ("kill-all-local-variables", Fkill_all_local_variables, Skill_all_local_variables,
   0, 0, 0,
-       /* Switch to Fundamental mode by killing current buffer's local variables.
+       doc: /* Switch to Fundamental mode by killing current buffer's local variables.
 Most local variable bindings are eliminated so that the default values
 become effective once more.  Also, the syntax table is set from
 `standard-syntax-table', the local keymap is set to nil,
@@ -2223,8 +2223,8 @@ As a special exception, local variables whose names have
 a non-nil `permanent-local' property are not eliminated by this function.
 
 The first thing this function does is run
-the normal hook `change-major-mode-hook'.  */
-       ())
+the normal hook `change-major-mode-hook'.  */)
+     ()
 {
   register Lisp_Object alist, sym, tem;
   Lisp_Object oalist;
@@ -3346,22 +3346,22 @@ fix_overlays_before (bp, prev, pos)
 }
 
 DEFUN ("overlayp", Foverlayp, Soverlayp, 1, 1, 0,
-       /* Return t if OBJECT is an overlay.  */
-       (object))
+       doc: /* Return t if OBJECT is an overlay.  */)
+     (object)
      Lisp_Object object;
 {
   return (OVERLAYP (object) ? Qt : Qnil);
 }
 
 DEFUN ("make-overlay", Fmake_overlay, Smake_overlay, 2, 5, 0,
-       /* Create a new overlay with range BEG to END in BUFFER.
+       doc: /* Create a new overlay with range BEG to END in BUFFER.
 If omitted, BUFFER defaults to the current buffer.
 BEG and END may be integers or markers.
 The fourth arg FRONT-ADVANCE, if non-nil, makes the
 front delimiter advance when text is inserted there.
 The fifth arg REAR-ADVANCE, if non-nil, makes the
-rear delimiter advance when text is inserted there.  */
-       (beg, end, buffer, front_advance, rear_advance))
+rear delimiter advance when text is inserted there.  */)
+     (beg, end, buffer, front_advance, rear_advance)
      Lisp_Object beg, end, buffer;
      Lisp_Object front_advance, rear_advance;
 {
@@ -3451,11 +3451,11 @@ modify_overlay (buf, start, end)
 Lisp_Object Fdelete_overlay ();
 
 DEFUN ("move-overlay", Fmove_overlay, Smove_overlay, 3, 4, 0,
-       /* Set the endpoints of OVERLAY to BEG and END in BUFFER.
+       doc: /* Set the endpoints of OVERLAY to BEG and END in BUFFER.
 If BUFFER is omitted, leave OVERLAY in the same buffer it inhabits now.
 If BUFFER is omitted, and OVERLAY is in no buffer, put it in the current
-buffer.  */
-       (overlay, beg, end, buffer))
+buffer.  */)
+     (overlay, beg, end, buffer)
      Lisp_Object overlay, beg, end, buffer;
 {
   struct buffer *b, *ob;
@@ -3555,8 +3555,8 @@ buffer.  */
 }
 
 DEFUN ("delete-overlay", Fdelete_overlay, Sdelete_overlay, 1, 1, 0,
-       /* Delete the overlay OVERLAY from its buffer.  */
-       (overlay))
+       doc: /* Delete the overlay OVERLAY from its buffer.  */)
+     (overlay)
      Lisp_Object overlay;
 {
   Lisp_Object buffer;
@@ -3595,8 +3595,8 @@ DEFUN ("delete-overlay", Fdelete_overlay, Sdelete_overlay, 1, 1, 0,
 /* Overlay dissection functions.  */
 
 DEFUN ("overlay-start", Foverlay_start, Soverlay_start, 1, 1, 0,
-       /* Return the position at which OVERLAY starts.  */
-       (overlay))
+       doc: /* Return the position at which OVERLAY starts.  */)
+     (overlay)
      Lisp_Object overlay;
 {
   CHECK_OVERLAY (overlay, 0);
@@ -3605,8 +3605,8 @@ DEFUN ("overlay-start", Foverlay_start, Soverlay_start, 1, 1, 0,
 }
 
 DEFUN ("overlay-end", Foverlay_end, Soverlay_end, 1, 1, 0,
-       /* Return the position at which OVERLAY ends.  */
-       (overlay))
+       doc: /* Return the position at which OVERLAY ends.  */)
+     (overlay)
      Lisp_Object overlay;
 {
   CHECK_OVERLAY (overlay, 0);
@@ -3615,8 +3615,8 @@ DEFUN ("overlay-end", Foverlay_end, Soverlay_end, 1, 1, 0,
 }
 
 DEFUN ("overlay-buffer", Foverlay_buffer, Soverlay_buffer, 1, 1, 0,
-       /* Return the buffer OVERLAY belongs to.  */
-       (overlay))
+       doc: /* Return the buffer OVERLAY belongs to.  */)
+     (overlay)
        Lisp_Object overlay;
 {
   CHECK_OVERLAY (overlay, 0);
@@ -3625,10 +3625,10 @@ DEFUN ("overlay-buffer", Foverlay_buffer, Soverlay_buffer, 1, 1, 0,
 }
 
 DEFUN ("overlay-properties", Foverlay_properties, Soverlay_properties, 1, 1, 0,
-       /* Return a list of the properties on OVERLAY.
+       doc: /* Return a list of the properties on OVERLAY.
 This is a copy of OVERLAY's plist; modifying its conses has no effect on
-OVERLAY.  */
-       (overlay))
+OVERLAY.  */)
+     (overlay)
     Lisp_Object overlay;
 {
   CHECK_OVERLAY (overlay, 0);
@@ -3638,8 +3638,8 @@ OVERLAY.  */
 
 
 DEFUN ("overlays-at", Foverlays_at, Soverlays_at, 1, 1, 0,
-       /* Return a list of the overlays that contain position POS.  */
-       (pos))
+       doc: /* Return a list of the overlays that contain position POS.  */)
+     (pos)
      Lisp_Object pos;
 {
   int noverlays;
@@ -3666,12 +3666,12 @@ DEFUN ("overlays-at", Foverlays_at, Soverlays_at, 1, 1, 0,
 }
 
 DEFUN ("overlays-in", Foverlays_in, Soverlays_in, 2, 2, 0,
-       /* Return a list of the overlays that overlap the region BEG ... END.
+       doc: /* Return a list of the overlays that overlap the region BEG ... END.
 Overlap means that at least one character is contained within the overlay
 and also contained within the specified region.
 Empty overlays are included in the result if they are located at BEG
-or between BEG and END.  */
-       (beg, end))
+or between BEG and END.  */)
+     (beg, end)
      Lisp_Object beg, end;
 {
   int noverlays;
@@ -3699,9 +3699,9 @@ or between BEG and END.  */
 
 DEFUN ("next-overlay-change", Fnext_overlay_change, Snext_overlay_change,
   1, 1, 0,
-       /* Return the next position after POS where an overlay starts or ends.
-If there are no more overlay boundaries after POS, return (point-max).  */
-       (pos))
+       doc: /* Return the next position after POS where an overlay starts or ends.
+If there are no more overlay boundaries after POS, return (point-max).  */)
+     (pos)
      Lisp_Object pos;
 {
   int noverlays;
@@ -3740,9 +3740,9 @@ If there are no more overlay boundaries after POS, return (point-max).  */
 
 DEFUN ("previous-overlay-change", Fprevious_overlay_change,
        Sprevious_overlay_change, 1, 1, 0,
-       /* Return the previous position before POS where an overlay starts or ends.
-If there are no more overlay boundaries before POS, return (point-min).  */
-       (pos))
+       doc: /* Return the previous position before POS where an overlay starts or ends.
+If there are no more overlay boundaries before POS, return (point-min).  */)
+     (pos)
      Lisp_Object pos;
 {
   int noverlays;
@@ -3773,13 +3773,13 @@ If there are no more overlay boundaries before POS, return (point-min).  */
 /* These functions are for debugging overlays.  */
 
 DEFUN ("overlay-lists", Foverlay_lists, Soverlay_lists, 0, 0, 0,
-       /* Return a pair of lists giving all the overlays of the current buffer.
+       doc: /* Return a pair of lists giving all the overlays of the current buffer.
 The car has all the overlays before the overlay center;
 the cdr has all the overlays after the overlay center.
 Recentering overlays moves overlays between these lists.
 The lists you get are copies, so that changing them has no effect.
-However, the overlays you get are the real objects that the buffer uses.  */
-       ())
+However, the overlays you get are the real objects that the buffer uses.  */)
+     ()
 {
   Lisp_Object before, after;
   before = current_buffer->overlays_before;
@@ -3793,8 +3793,8 @@ However, the overlays you get are the real objects that the buffer uses.  */
 }
 
 DEFUN ("overlay-recenter", Foverlay_recenter, Soverlay_recenter, 1, 1, 0,
-       /* Recenter the overlays of the current buffer around position POS.  */
-       (pos))
+       doc: /* Recenter the overlays of the current buffer around position POS.  */)
+     (pos)
      Lisp_Object pos;
 {
   CHECK_NUMBER_COERCE_MARKER (pos, 0);
@@ -3804,8 +3804,8 @@ DEFUN ("overlay-recenter", Foverlay_recenter, Soverlay_recenter, 1, 1, 0,
 }
 
 DEFUN ("overlay-get", Foverlay_get, Soverlay_get, 2, 2, 0,
-       /* Get the property of overlay OVERLAY with property name PROP.  */
-       (overlay, prop))
+       doc: /* Get the property of overlay OVERLAY with property name PROP.  */)
+     (overlay, prop)
      Lisp_Object overlay, prop;
 {
   Lisp_Object plist, fallback;
@@ -3833,8 +3833,8 @@ DEFUN ("overlay-get", Foverlay_get, Soverlay_get, 2, 2, 0,
 }
 
 DEFUN ("overlay-put", Foverlay_put, Soverlay_put, 3, 3, 0,
-       /* Set one property of overlay OVERLAY: give property PROP value VALUE.  */
-       (overlay, prop, value))
+       doc: /* Set one property of overlay OVERLAY: give property PROP value VALUE.  */)
+     (overlay, prop, value)
      Lisp_Object overlay, prop, value;
 {
   Lisp_Object tail, buffer;
@@ -5011,118 +5011,118 @@ syms_of_buffer ()
      buffer_defaults will all be marked via Vbuffer_defaults.  */
 
   DEFVAR_LISP_NOPRO ("default-mode-line-format",
-                     &buffer_defaults.mode_line_format
-                     /* Default value of `mode-line-format' for buffers that don't override it.
+                     &buffer_defaults.mode_line_format,
+                     doc: /* Default value of `mode-line-format' for buffers that don't override it.
 This is the same as (default-value 'mode-line-format).  */);
 
   DEFVAR_LISP_NOPRO ("default-header-line-format",
-                     &buffer_defaults.header_line_format
-                     /* Default value of `header-line-format' for buffers that don't override it.
+                     &buffer_defaults.header_line_format,
+                     doc: /* Default value of `header-line-format' for buffers that don't override it.
 This is the same as (default-value 'header-line-format).  */);
 
-  DEFVAR_LISP_NOPRO ("default-cursor-type", &buffer_defaults.cursor_type
-                     /* Default value of `cursor-type' for buffers that don't override it.
+  DEFVAR_LISP_NOPRO ("default-cursor-type", &buffer_defaults.cursor_type,
+                     doc: /* Default value of `cursor-type' for buffers that don't override it.
 This is the same as (default-value 'cursor-type).  */);
 
   DEFVAR_LISP_NOPRO ("default-line-spacing",
-                     &buffer_defaults.extra_line_spacing
-                     /* Default value of `line-spacing' for buffers that don't override it.
+                     &buffer_defaults.extra_line_spacing,
+                     doc: /* Default value of `line-spacing' for buffers that don't override it.
 This is the same as (default-value 'line-spacing).  */);
 
   DEFVAR_LISP_NOPRO ("default-abbrev-mode",
-              &buffer_defaults.abbrev_mode
-                     /* Default value of `abbrev-mode' for buffers that do not override it.
+              &buffer_defaults.abbrev_mode,
+                     doc: /* Default value of `abbrev-mode' for buffers that do not override it.
 This is the same as (default-value 'abbrev-mode).  */);
 
   DEFVAR_LISP_NOPRO ("default-ctl-arrow",
-              &buffer_defaults.ctl_arrow
-                     /* Default value of `ctl-arrow' for buffers that do not override it.
+              &buffer_defaults.ctl_arrow,
+                     doc: /* Default value of `ctl-arrow' for buffers that do not override it.
 This is the same as (default-value 'ctl-arrow).  */);
 
    DEFVAR_LISP_NOPRO ("default-direction-reversed",
-              &buffer_defaults.direction_reversed
-                      /* Default value of `direction_reversed' for buffers that do not override it.
+              &buffer_defaults.direction_reversed,
+                      doc: /* Default value of `direction_reversed' for buffers that do not override it.
 This is the same as (default-value 'direction-reversed).  */);
  
    DEFVAR_LISP_NOPRO ("default-enable-multibyte-characters",
-              &buffer_defaults.enable_multibyte_characters
-                      /* *Default value of `enable-multibyte-characters' for buffers not overriding it.
+              &buffer_defaults.enable_multibyte_characters,
+                      doc: /* *Default value of `enable-multibyte-characters' for buffers not overriding it.
 This is the same as (default-value 'enable-multibyte-characters).  */);
  
    DEFVAR_LISP_NOPRO ("default-buffer-file-coding-system",
-              &buffer_defaults.buffer_file_coding_system
-                      /* Default value of `buffer-file-coding-system' for buffers not overriding it.
+              &buffer_defaults.buffer_file_coding_system,
+                      doc: /* Default value of `buffer-file-coding-system' for buffers not overriding it.
 This is the same as (default-value 'buffer-file-coding-system).  */);
  
   DEFVAR_LISP_NOPRO ("default-truncate-lines",
-              &buffer_defaults.truncate_lines
-    /* Default value of `truncate-lines' for buffers that do not override it.
+              &buffer_defaults.truncate_lines,
+    doc: /* Default value of `truncate-lines' for buffers that do not override it.
 This is the same as (default-value 'truncate-lines).  */);
 
   DEFVAR_LISP_NOPRO ("default-fill-column",
-              &buffer_defaults.fill_column
-    /* Default value of `fill-column' for buffers that do not override it.
+              &buffer_defaults.fill_column,
+    doc: /* Default value of `fill-column' for buffers that do not override it.
 This is the same as (default-value 'fill-column).  */);
 
   DEFVAR_LISP_NOPRO ("default-left-margin",
-              &buffer_defaults.left_margin
-    /* Default value of `left-margin' for buffers that do not override it.
+              &buffer_defaults.left_margin,
+    doc: /* Default value of `left-margin' for buffers that do not override it.
 This is the same as (default-value 'left-margin).  */);
 
   DEFVAR_LISP_NOPRO ("default-tab-width",
-              &buffer_defaults.tab_width
-    /* Default value of `tab-width' for buffers that do not override it.
+              &buffer_defaults.tab_width,
+    doc: /* Default value of `tab-width' for buffers that do not override it.
 This is the same as (default-value 'tab-width).  */);
 
   DEFVAR_LISP_NOPRO ("default-case-fold-search",
-              &buffer_defaults.case_fold_search
-    /* Default value of `case-fold-search' for buffers that don't override it.
+              &buffer_defaults.case_fold_search,
+    doc: /* Default value of `case-fold-search' for buffers that don't override it.
 This is the same as (default-value 'case-fold-search).  */);
 
 #ifdef DOS_NT
   DEFVAR_LISP_NOPRO ("default-buffer-file-type", 
-                     &buffer_defaults.buffer_file_type
-    /* Default file type for buffers that do not override it.
+                     &buffer_defaults.buffer_file_type,
+    doc: /* Default file type for buffers that do not override it.
 This is the same as (default-value 'buffer-file-type).
 The file type is nil for text, t for binary.  */);
 #endif
 
   DEFVAR_LISP_NOPRO ("default-left-margin-width",
-              &buffer_defaults.left_margin_width
-    /* Default value of `left-margin-width' for buffers that don't override it.
+              &buffer_defaults.left_margin_width,
+    doc: /* Default value of `left-margin-width' for buffers that don't override it.
 This is the same as (default-value 'left-margin-width).  */);
 
   DEFVAR_LISP_NOPRO ("default-right-margin-width",
-              &buffer_defaults.right_margin_width
-    /* Default value of `right_margin_width' for buffers that don't override it.
+              &buffer_defaults.right_margin_width,
+    doc: /* Default value of `right_margin_width' for buffers that don't override it.
 This is the same as (default-value 'right-margin-width).  */);
   
   DEFVAR_LISP_NOPRO ("default-indicate-empty-lines",
-              &buffer_defaults.indicate_empty_lines
-    /* Default value of `indicate-empty-lines' for buffers that don't override it.
+              &buffer_defaults.indicate_empty_lines,
+    doc: /* Default value of `indicate-empty-lines' for buffers that don't override it.
 This is the same as (default-value 'indicate-empty-lines).  */);
   
   DEFVAR_LISP_NOPRO ("default-scroll-up-aggressively",
-              &buffer_defaults.scroll_up_aggressively
-    /* Default value of `scroll-up-aggressively' for buffers that
+              &buffer_defaults.scroll_up_aggressively,
+    doc: /* Default value of `scroll-up-aggressively' for buffers that
 don't override it.  This is the same as (default-value
 'scroll-up-aggressively).  */);
   
   DEFVAR_LISP_NOPRO ("default-scroll-down-aggressively",
-              &buffer_defaults.scroll_down_aggressively
-    /* Default value of `scroll-down-aggressively' for buffers that
+              &buffer_defaults.scroll_down_aggressively,
+    doc: /* Default value of `scroll-down-aggressively' for buffers that
 don't override it.  This is the same as (default-value
 'scroll-down-aggressively).  */);
   
   DEFVAR_PER_BUFFER ("header-line-format",
                      &current_buffer->header_line_format,
-                     Qnil
-   /* Analogous to `mode-line-format', but for the mode line that can be
+                     Qnil,
+   doc: /* Analogous to `mode-line-format', but for the mode line that can be
 displayed at the top of a window.  */);
   
   DEFVAR_PER_BUFFER ("mode-line-format", &current_buffer->mode_line_format,
-    Qnil
-    /* Template for displaying mode line for current buffer.
+    Qnil,
+    doc: /* Template for displaying mode line for current buffer.
 Each buffer has its own value of this variable.
 Value may be nil, a string, a symbol or a list or cons cell.
 A value of nil means don't display a mode line.
@@ -5163,48 +5163,48 @@ A string is printed verbatim in the mode line except for %-constructs:
   %% -- print %.   %- -- print infinitely many dashes.
 Decimal digits after the % specify field width to which to pad.  */);
 
-  DEFVAR_LISP_NOPRO ("default-major-mode", &buffer_defaults.major_mode
-    /* *Major mode for new buffers.  Defaults to `fundamental-mode'.
+  DEFVAR_LISP_NOPRO ("default-major-mode", &buffer_defaults.major_mode,
+    doc: /* *Major mode for new buffers.  Defaults to `fundamental-mode'.
 nil here means use current buffer's major mode.  */);
 
   DEFVAR_PER_BUFFER ("major-mode", &current_buffer->major_mode,
-                     make_number (Lisp_Symbol)
-    /* Symbol for current buffer's major mode.  */);
+                     make_number (Lisp_Symbol),
+    doc: /* Symbol for current buffer's major mode.  */);
 
   DEFVAR_PER_BUFFER ("mode-name", &current_buffer->mode_name,
-                     make_number (Lisp_String)
-    /* Pretty name of current buffer's major mode (a string).  */);
+                     make_number (Lisp_String),
+    doc: /* Pretty name of current buffer's major mode (a string).  */);
 
-  DEFVAR_PER_BUFFER ("abbrev-mode", &current_buffer->abbrev_mode, Qnil
-    /* Non-nil turns on automatic expansion of abbrevs as they are inserted.  */);
+  DEFVAR_PER_BUFFER ("abbrev-mode", &current_buffer->abbrev_mode, Qnil,
+    doc: /* Non-nil turns on automatic expansion of abbrevs as they are inserted.  */);
 
   DEFVAR_PER_BUFFER ("case-fold-search", &current_buffer->case_fold_search,
-                     Qnil
-    /* *Non-nil if searches and matches should ignore case.  */);
+                     Qnil,
+    doc: /* *Non-nil if searches and matches should ignore case.  */);
 
   DEFVAR_PER_BUFFER ("fill-column", &current_buffer->fill_column,
-                     make_number (Lisp_Int)
-    /* *Column beyond which automatic line-wrapping should happen.  */);
+                     make_number (Lisp_Int),
+    doc: /* *Column beyond which automatic line-wrapping should happen.  */);
 
   DEFVAR_PER_BUFFER ("left-margin", &current_buffer->left_margin,
-                     make_number (Lisp_Int)
-    /* *Column for the default indent-line-function to indent to.
+                     make_number (Lisp_Int),
+    doc: /* *Column for the default indent-line-function to indent to.
 Linefeed indents to this column in Fundamental mode.  */);
 
   DEFVAR_PER_BUFFER ("tab-width", &current_buffer->tab_width,
-                     make_number (Lisp_Int)
-    /* *Distance between tab stops (for display of tab characters), in columns.  */);
+                     make_number (Lisp_Int),
+    doc: /* *Distance between tab stops (for display of tab characters), in columns.  */);
 
-  DEFVAR_PER_BUFFER ("ctl-arrow", &current_buffer->ctl_arrow, Qnil
-    /* *Non-nil means display control chars with uparrow.
+  DEFVAR_PER_BUFFER ("ctl-arrow", &current_buffer->ctl_arrow, Qnil,
+    doc: /* *Non-nil means display control chars with uparrow.
 A value of nil means use backslash and octal digits.
 This variable does not apply to characters whose display is specified
 in the current display table (if there is one).  */);
 
   DEFVAR_PER_BUFFER ("enable-multibyte-characters",
                      &current_buffer->enable_multibyte_characters,
-                     make_number (-1)
-    /* Non-nil means the buffer contents are regarded as multi-byte characters.
+                     make_number (-1),
+    doc: /* Non-nil means the buffer contents are regarded as multi-byte characters.
 Otherwise they are regarded as unibyte.  This affects the display,
 file I/O and the behavior of various editing commands.
 
@@ -5215,8 +5215,8 @@ See also variable `default-enable-multibyte-characters' and Info node
 `(elisp)Text Representations'.  */);
 
   DEFVAR_PER_BUFFER ("buffer-file-coding-system",
-                     &current_buffer->buffer_file_coding_system, Qnil
-    /* Coding system to be used for encoding the buffer contents on saving.
+                     &current_buffer->buffer_file_coding_system, Qnil,
+    doc: /* Coding system to be used for encoding the buffer contents on saving.
 This variable applies to saving the buffer, and also to `write-region'
 and other functions that use `write-region'.
 It does not apply to sending output to subprocesses, however.
@@ -5230,11 +5230,11 @@ The variable `coding-system-for-write', if non-nil, overrides this variable.
 This variable is never applied to a way of decoding a file while reading it.  */);
 
   DEFVAR_PER_BUFFER ("direction-reversed", &current_buffer->direction_reversed,
-                     Qnil
-    /* *Non-nil means lines in the buffer are displayed right to left.  */);
+                     Qnil,
+    doc: /* *Non-nil means lines in the buffer are displayed right to left.  */);
 
-  DEFVAR_PER_BUFFER ("truncate-lines", &current_buffer->truncate_lines, Qnil
-    /* *Non-nil means do not display continuation lines;
+  DEFVAR_PER_BUFFER ("truncate-lines", &current_buffer->truncate_lines, Qnil,
+    doc: /* *Non-nil means do not display continuation lines;
 give each line of text one screen line.
 
 Note that this is overridden by the variable
@@ -5243,57 +5243,57 @@ and this buffer is not full-frame width.  */);
 
 #ifdef DOS_NT
   DEFVAR_PER_BUFFER ("buffer-file-type", &current_buffer->buffer_file_type,
-                     Qnil
-    /* Non-nil if the visited file is a binary file.
+                     Qnil,
+    doc: /* Non-nil if the visited file is a binary file.
 This variable is meaningful on MS-DOG and Windows NT.
 On those systems, it is automatically local in every buffer.
 On other systems, this variable is normally always nil.  */);
 #endif
 
   DEFVAR_PER_BUFFER ("default-directory", &current_buffer->directory,
-                     make_number (Lisp_String)
-    /* Name of default directory of current buffer.  Should end with slash.
+                     make_number (Lisp_String),
+    doc: /* Name of default directory of current buffer.  Should end with slash.
 To interactively change the default directory, use command `cd'.  */);
 
   DEFVAR_PER_BUFFER ("auto-fill-function", &current_buffer->auto_fill_function,
-                     Qnil
-    /* Function called (if non-nil) to perform auto-fill.
+                     Qnil,
+    doc: /* Function called (if non-nil) to perform auto-fill.
 It is called after self-inserting any character specified in
 the `auto-fill-chars' table.
 NOTE: This variable is not a hook;
 its value may not be a list of functions.  */);
 
   DEFVAR_PER_BUFFER ("buffer-file-name", &current_buffer->filename,
-                     make_number (Lisp_String)
-    /* Name of file visited in current buffer, or nil if not visiting a file.  */);
+                     make_number (Lisp_String),
+    doc: /* Name of file visited in current buffer, or nil if not visiting a file.  */);
 
   DEFVAR_PER_BUFFER ("buffer-file-truename", &current_buffer->file_truename,
-                     make_number (Lisp_String)
-    /* Abbreviated truename of file visited in current buffer, or nil if none.
+                     make_number (Lisp_String),
+    doc: /* Abbreviated truename of file visited in current buffer, or nil if none.
 The truename of a file is calculated by `file-truename'
 and then abbreviated with `abbreviate-file-name'.  */);
 
   DEFVAR_PER_BUFFER ("buffer-auto-save-file-name",
                      &current_buffer->auto_save_file_name,
-                     make_number (Lisp_String)
-    /* Name of file for auto-saving current buffer,
+                     make_number (Lisp_String),
+    doc: /* Name of file for auto-saving current buffer,
 or nil if buffer should not be auto-saved.  */);
 
-  DEFVAR_PER_BUFFER ("buffer-read-only", &current_buffer->read_only, Qnil
-    /* Non-nil if this buffer is read-only.  */);
+  DEFVAR_PER_BUFFER ("buffer-read-only", &current_buffer->read_only, Qnil,
+    doc: /* Non-nil if this buffer is read-only.  */);
 
-  DEFVAR_PER_BUFFER ("buffer-backed-up", &current_buffer->backed_up, Qnil
-    /* Non-nil if this buffer's file has been backed up.
+  DEFVAR_PER_BUFFER ("buffer-backed-up", &current_buffer->backed_up, Qnil,
+    doc: /* Non-nil if this buffer's file has been backed up.
 Backing up is done before the first time the file is saved.  */);
 
   DEFVAR_PER_BUFFER ("buffer-saved-size", &current_buffer->save_length,
-                     make_number (Lisp_Int)
-    /* Length of current buffer when last read in, saved or auto-saved.
+                     make_number (Lisp_Int),
+    doc: /* Length of current buffer when last read in, saved or auto-saved.
 0 initially.  */);
 
   DEFVAR_PER_BUFFER ("selective-display", &current_buffer->selective_display,
-                     Qnil
-    /* Non-nil enables selective display:
+                     Qnil,
+    doc: /* Non-nil enables selective display:
 Integer N as value means display only lines
  that start with less than n columns of space.
 A value of t means, after a ^M, all the rest of the line is invisible.
@@ -5302,12 +5302,12 @@ A value of t means, after a ^M, all the rest of the line is invisible.
 #ifndef old
   DEFVAR_PER_BUFFER ("selective-display-ellipses",
                     &current_buffer->selective_display_ellipses,
-                     Qnil
-    /* t means display ... on previous line when a line is invisible.  */);
+                     Qnil,
+    doc: /* t means display ... on previous line when a line is invisible.  */);
 #endif
 
-  DEFVAR_PER_BUFFER ("overwrite-mode", &current_buffer->overwrite_mode, Qnil
-    /* Non-nil if self-insertion should replace existing text.
+  DEFVAR_PER_BUFFER ("overwrite-mode", &current_buffer->overwrite_mode, Qnil,
+    doc: /* Non-nil if self-insertion should replace existing text.
 The value should be one of `overwrite-mode-textual',
 `overwrite-mode-binary', or nil.
 If it is `overwrite-mode-textual', self-insertion still
@@ -5316,8 +5316,8 @@ until the tab is filled in.
 If `overwrite-mode-binary', self-insertion replaces newlines and tabs too.  */);
 
   DEFVAR_PER_BUFFER ("buffer-display-table", &current_buffer->display_table,
-                     Qnil
-    /* Display table that controls display of the contents of current buffer.
+                     Qnil,
+    doc: /* Display table that controls display of the contents of current buffer.
 
 If this variable is nil, the value of `standard-display-table' is used.
 Each window can have its own, overriding display table, see
@@ -5353,31 +5353,31 @@ In addition, a char-table has six extra slots to control the display of:
 See also the functions `display-table-slot' and `set-display-table-slot'.  */);
 
   DEFVAR_PER_BUFFER ("left-margin-width", &current_buffer->left_margin_width,
-                     Qnil
-    /* *Width of left marginal area for display of a buffer.
+                     Qnil,
+    doc: /* *Width of left marginal area for display of a buffer.
 A value of nil means no marginal area.  */);
   
   DEFVAR_PER_BUFFER ("right-margin-width", &current_buffer->right_margin_width,
-                     Qnil
-    /* *Width of right marginal area for display of a buffer.
+                     Qnil,
+    doc: /* *Width of right marginal area for display of a buffer.
 A value of nil means no marginal area.  */);
   
   DEFVAR_PER_BUFFER ("indicate-empty-lines",
-                     &current_buffer->indicate_empty_lines, Qnil
-    /* *Visually indicate empty lines after the buffer end.
+                     &current_buffer->indicate_empty_lines, Qnil,
+    doc: /* *Visually indicate empty lines after the buffer end.
 If non-nil, a bitmap is displayed in the left fringe of a window on
 window-systems.  */);
   
   DEFVAR_PER_BUFFER ("scroll-up-aggressively",
-                     &current_buffer->scroll_up_aggressively, Qnil
-    /* *If a number, scroll display up aggressively.
+                     &current_buffer->scroll_up_aggressively, Qnil,
+    doc: /* *If a number, scroll display up aggressively.
 If scrolling a window because point is above the window start, choose
 a new window start so that point ends up that fraction of the window's
 height from the top of the window.  */);
   
   DEFVAR_PER_BUFFER ("scroll-down-aggressively",
-                     &current_buffer->scroll_down_aggressively, Qnil
-    /* *If a number, scroll display down aggressively.
+                     &current_buffer->scroll_down_aggressively, Qnil,
+    doc: /* *If a number, scroll display down aggressively.
 If scrolling a window because point is below the window end, choose
 a new window start so that point ends up that fraction of the window's
 height from the bottom of the window.  */);
@@ -5386,8 +5386,8 @@ height from the bottom of the window.  */);
     "Don't ask.");
 */
 
-  DEFVAR_LISP ("before-change-functions", &Vbefore_change_functions
-               /* List of functions to call before each text change.
+  DEFVAR_LISP ("before-change-functions", &Vbefore_change_functions,
+               doc: /* List of functions to call before each text change.
 Two arguments are passed to each function: the positions of
 the beginning and end of the range of old text to be changed.
 \(For an insertion, the beginning and end are at the same place.)
@@ -5405,8 +5405,8 @@ the variable's value remains nil.  That prevents the error
 from happening repeatedly and making Emacs nonfunctional.  */);
   Vbefore_change_functions = Qnil;
 
-  DEFVAR_LISP ("after-change-functions", &Vafter_change_functions
-               /* List of function to call after each text change.
+  DEFVAR_LISP ("after-change-functions", &Vafter_change_functions,
+               doc: /* List of function to call after each text change.
 Three arguments are passed to each function: the positions of
 the beginning and end of the range of changed text,
 and the length in bytes of the pre-change text replaced by that range.
@@ -5426,13 +5426,13 @@ the variable's value remains nil.  That prevents the error
 from happening repeatedly and making Emacs nonfunctional.  */);
   Vafter_change_functions = Qnil;
 
-  DEFVAR_LISP ("first-change-hook", &Vfirst_change_hook
-  /* A list of functions to call before changing a buffer which is unmodified.
+  DEFVAR_LISP ("first-change-hook", &Vfirst_change_hook,
+  doc: /* A list of functions to call before changing a buffer which is unmodified.
 The functions are run using the `run-hooks' function.  */);
   Vfirst_change_hook = Qnil;
 
-  DEFVAR_PER_BUFFER ("buffer-undo-list", &current_buffer->undo_list, Qnil
-                     /* List of undo entries in current buffer.
+  DEFVAR_PER_BUFFER ("buffer-undo-list", &current_buffer->undo_list, Qnil,
+                     doc: /* List of undo entries in current buffer.
 Recent changes come first; older changes follow newer.
 
 An entry (BEG . END) represents an insertion which begins at
@@ -5464,11 +5464,11 @@ between two undo boundaries as a single step to be undone.
 
 If the value of the variable is t, undo information is not recorded.  */);
 
-  DEFVAR_PER_BUFFER ("mark-active", &current_buffer->mark_active, Qnil
-                     /* Non-nil means the mark and region are currently active in this buffer.  */);
+  DEFVAR_PER_BUFFER ("mark-active", &current_buffer->mark_active, Qnil,
+                     doc: /* Non-nil means the mark and region are currently active in this buffer.  */);
 
-  DEFVAR_PER_BUFFER ("cache-long-line-scans", &current_buffer->cache_long_line_scans, Qnil
-                     /* Non-nil means that Emacs should use caches to handle long lines more quickly.
+  DEFVAR_PER_BUFFER ("cache-long-line-scans", &current_buffer->cache_long_line_scans, Qnil,
+                     doc: /* Non-nil means that Emacs should use caches to handle long lines more quickly.
 
 Normally, the line-motion functions work by scanning the buffer for
 newlines.  Columnar operations (like move-to-column and
@@ -5495,17 +5495,17 @@ maintained internally by the Emacs primitives.  Enabling or disabling
 the cache should not affect the behavior of any of the motion
 functions; it should only affect their performance.  */);
 
-  DEFVAR_PER_BUFFER ("point-before-scroll", &current_buffer->point_before_scroll, Qnil
-                     /* Value of point before the last series of scroll operations, or nil.  */);
+  DEFVAR_PER_BUFFER ("point-before-scroll", &current_buffer->point_before_scroll, Qnil,
+                     doc: /* Value of point before the last series of scroll operations, or nil.  */);
 
-  DEFVAR_PER_BUFFER ("buffer-file-format", &current_buffer->file_format, Qnil
-                     /* List of formats to use when saving this buffer.
+  DEFVAR_PER_BUFFER ("buffer-file-format", &current_buffer->file_format, Qnil,
+                     doc: /* List of formats to use when saving this buffer.
 Formats are defined by `format-alist'.  This variable is
 set when a file is visited.  Automatically local in all buffers.  */);
 
   DEFVAR_PER_BUFFER ("buffer-invisibility-spec",
-                     &current_buffer->invisibility_spec, Qnil
-                     /* Invisibility spec of this buffer.
+                     &current_buffer->invisibility_spec, Qnil,
+                     doc: /* Invisibility spec of this buffer.
 The default is t, which means that text is invisible
 if it has a non-nil `invisible' property.
 If the value is a list, a text character is invisible if its `invisible'
@@ -5515,34 +5515,34 @@ then characters with property value PROP are invisible,
 and they have an ellipsis as well if ELLIPSIS is non-nil.  */);
 
   DEFVAR_PER_BUFFER ("buffer-display-count",
-                     &current_buffer->display_count, Qnil
-                     /* A number incremented each time this buffer is displayed in a window.
+                     &current_buffer->display_count, Qnil,
+                     doc: /* A number incremented each time this buffer is displayed in a window.
 The function `set-window-buffer' increments it.  */);
 
   DEFVAR_PER_BUFFER ("buffer-display-time",
-                     &current_buffer->display_time, Qnil
-                     /* Time stamp updated each time this buffer is displayed in a window.
+                     &current_buffer->display_time, Qnil,
+                     doc: /* Time stamp updated each time this buffer is displayed in a window.
 The function `set-window-buffer' updates this variable
 to the value obtained by calling `current-time'.
 If the buffer has never been shown in a window, the value is nil.  */);
 
-  DEFVAR_LISP ("transient-mark-mode", &Vtransient_mark_mode
-               /* *Non-nil means deactivate the mark when the buffer contents change.
+  DEFVAR_LISP ("transient-mark-mode", &Vtransient_mark_mode,
+               doc: /* *Non-nil means deactivate the mark when the buffer contents change.
 Non-nil also enables highlighting of the region whenever the mark is active.
 The variable `highlight-nonselected-windows' controls whether to highlight
 all windows or just the selected window.  */);
   Vtransient_mark_mode = Qnil;
 
-  DEFVAR_LISP ("inhibit-read-only", &Vinhibit_read_only
-               /* *Non-nil means disregard read-only status of buffers or characters.
+  DEFVAR_LISP ("inhibit-read-only", &Vinhibit_read_only,
+               doc: /* *Non-nil means disregard read-only status of buffers or characters.
 If the value is t, disregard `buffer-read-only' and all `read-only'
 text properties.  If the value is a list, disregard `buffer-read-only'
 and disregard a `read-only' text property if the property value
 is a member of the list.  */);
   Vinhibit_read_only = Qnil;
 
-  DEFVAR_PER_BUFFER ("cursor-type", &current_buffer->cursor_type, Qnil
-                     /* Cursor to use in window displaying this buffer.
+  DEFVAR_PER_BUFFER ("cursor-type", &current_buffer->cursor_type, Qnil,
+                     doc: /* Cursor to use in window displaying this buffer.
 Values are interpreted as follows:
 
   t             use the cursor specified for the frame
@@ -5552,12 +5552,12 @@ Values are interpreted as follows:
   others        display a box cursor.  */);
 
   DEFVAR_PER_BUFFER ("line-spacing",
-                     &current_buffer->extra_line_spacing, Qnil
-                     /* Additional space to put between lines when displaying a buffer.
+                     &current_buffer->extra_line_spacing, Qnil,
+                     doc: /* Additional space to put between lines when displaying a buffer.
 The space is measured in pixels, and put below lines on window systems.  */);
 
-  DEFVAR_LISP ("kill-buffer-query-functions", &Vkill_buffer_query_functions
-    /* List of functions called with no args to query before killing a buffer.  */);
+  DEFVAR_LISP ("kill-buffer-query-functions", &Vkill_buffer_query_functions,
+    doc: /* List of functions called with no args to query before killing a buffer.  */);
   Vkill_buffer_query_functions = Qnil;
 
   defsubr (&Sbuffer_live_p);
diff --git a/src/dispnew.c b/src/dispnew.c
index d5cbb7d7db5..d75aa837c87 100644
--- a/src/dispnew.c
+++ b/src/dispnew.c
@@ -19,8 +19,6 @@ along with GNU Emacs; see the file COPYING.  If not, write to
 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA 02111-1307, USA.  */
 
-#define DOC_STRINGS_IN_COMMENTS
-
 #include <config.h>
 #include <signal.h>
 #include <stdio.h>
@@ -412,8 +410,8 @@ add_frame_display_history (f, paused_p)
 
 DEFUN ("dump-redisplay-history", Fdump_redisplay_history,
        Sdump_redisplay_history, 0, 0, "",
-       /* Dump redisplay history to stderr.  */
-       ())
+       doc: /* Dump redisplay history to stderr.  */)
+     ()
 {
   int i;
 
@@ -3307,8 +3305,8 @@ window_to_frame_hpos (w, hpos)
  **********************************************************************/
 
 DEFUN ("redraw-frame", Fredraw_frame, Sredraw_frame, 1, 1, 0,
-       /* Clear frame FRAME and output again what is supposed to appear on it.  */
-       (frame))
+       doc: /* Clear frame FRAME and output again what is supposed to appear on it.  */)
+     (frame)
      Lisp_Object frame;
 {
   struct frame *f;
@@ -3353,8 +3351,8 @@ redraw_frame (f)
 
 
 DEFUN ("redraw-display", Fredraw_display, Sredraw_display, 0, 0, "",
-       /* Clear and redisplay all visible frames.  */
-       ())
+       doc: /* Clear and redisplay all visible frames.  */)
+     ()
 {
   Lisp_Object tail, frame;
 
@@ -6043,9 +6041,9 @@ change_frame_size_1 (f, newheight, newwidth, pretend, delay, safe)
 
 DEFUN ("open-termscript", Fopen_termscript, Sopen_termscript,
        1, 1, "FOpen termscript file: ",
-       /* Start writing all terminal output to FILE as well as the terminal.
-FILE = nil means just close any termscript file currently open.  */
-       (file))
+       doc: /* Start writing all terminal output to FILE as well as the terminal.
+FILE = nil means just close any termscript file currently open.  */)
+     (file)
      Lisp_Object file;
 {
   if (termscript != 0) fclose (termscript);
@@ -6064,9 +6062,9 @@ FILE = nil means just close any termscript file currently open.  */
 
 DEFUN ("send-string-to-terminal", Fsend_string_to_terminal,
        Ssend_string_to_terminal, 1, 1, 0,
-       /* Send STRING to the terminal without alteration.
-Control characters in STRING will have terminal-dependent effects.  */
-       (string))
+       doc: /* Send STRING to the terminal without alteration.
+Control characters in STRING will have terminal-dependent effects.  */)
+     (string)
      Lisp_Object string;
 {
   /* ??? Perhaps we should do something special for multibyte strings here.  */
@@ -6084,10 +6082,10 @@ Control characters in STRING will have terminal-dependent effects.  */
 
 
 DEFUN ("ding", Fding, Sding, 0, 1, 0,
-       /* Beep, or flash the screen.
+       doc: /* Beep, or flash the screen.
 Also, unless an argument is given,
-terminate any keyboard macro currently executing.  */
-       (arg))
+terminate any keyboard macro currently executing.  */)
+     (arg)
   Lisp_Object arg;
 {
   if (!NILP (arg))
@@ -6123,13 +6121,13 @@ bitch_at_user ()
  ***********************************************************************/
 
 DEFUN ("sleep-for", Fsleep_for, Ssleep_for, 1, 2, 0,
-       /* Pause, without updating display, for SECONDS seconds.
+       doc: /* Pause, without updating display, for SECONDS seconds.
 SECONDS may be a floating-point value, meaning that you can wait for a
 fraction of a second.  Optional second arg MILLISECONDS specifies an
 additional wait period, in milliseconds; this may be useful if your
 Emacs was built without floating point support.
-\(Not all operating systems support waiting for a fraction of a second.)  */
-       (seconds, milliseconds))
+\(Not all operating systems support waiting for a fraction of a second.)  */)
+     (seconds, milliseconds)
      Lisp_Object seconds, milliseconds;
 {
   int sec, usec;
@@ -6246,7 +6244,7 @@ sit_for (sec, usec, reading, display, initial_display)
 
 
 DEFUN ("sit-for", Fsit_for, Ssit_for, 1, 3, 0,
-  /* Perform redisplay, then wait for SECONDS seconds or until input is available.
+  doc: /* Perform redisplay, then wait for SECONDS seconds or until input is available.
 SECONDS may be a floating-point value, meaning that you can wait for a
 fraction of a second.  Optional second arg MILLISECONDS specifies an
 additional wait period, in milliseconds; this may be useful if your
@@ -6255,8 +6253,8 @@ Emacs was built without floating point support.
 Optional third arg NODISP non-nil means don't redisplay, just wait for input.
 Redisplay is preempted as always if input arrives, and does not happen
 if input is available before it starts.
-Value is t if waited the full time with no input arriving.  */
-       (seconds, milliseconds, nodisp))
+Value is t if waited the full time with no input arriving.  */)
+     (seconds, milliseconds, nodisp)
      Lisp_Object seconds, milliseconds, nodisp;
 {
   int sec, usec;
@@ -6297,14 +6295,14 @@ static Lisp_Object frame_and_buffer_state;
 
 DEFUN ("frame-or-buffer-changed-p", Fframe_or_buffer_changed_p,
        Sframe_or_buffer_changed_p, 0, 0, 0,
-  /* Return non-nil if the frame and buffer state appears to have changed.
+  doc: /* Return non-nil if the frame and buffer state appears to have changed.
 The state variable is an internal vector containing all frames and buffers,
 aside from buffers whose names start with space,
 along with the buffers' read-only and modified flags, which allows a fast
 check to see whether the menu bars might need to be recomputed.
 If this function returns non-nil, it updates the internal vector to reflect
-the current state.  */
-       ())
+the current state.  */)
+     ()
 {
   Lisp_Object tail, frame, buf;
   Lisp_Object *vecp;
@@ -6569,11 +6567,11 @@ For types not defined in VMS, use  define emacs_term \"TYPE\".\n\
 
 DEFUN ("internal-show-cursor", Finternal_show_cursor,
        Sinternal_show_cursor, 2, 2, 0,
-       /* Set the cursor-visibility flag of WINDOW to SHOW.
+       doc: /* Set the cursor-visibility flag of WINDOW to SHOW.
 WINDOW nil means use the selected window.  SHOW non-nil means
 show a cursor in WINDOW in the next redisplay.  SHOW nil means
-don't show a cursor.  */
-       (window, show))
+don't show a cursor.  */)
+     (window, show)
      Lisp_Object window, show;
 {
   /* Don't change cursor state while redisplaying.  This could confuse
@@ -6594,9 +6592,9 @@ don't show a cursor.  */
 
 DEFUN ("internal-show-cursor-p", Finternal_show_cursor_p,
        Sinternal_show_cursor_p, 0, 1, 0,
-   /* Value is non-nil if next redisplay will display a cursor in WINDOW.
-WINDOW nil or omitted means report on the selected window.  */
-       (window))
+   doc: /* Value is non-nil if next redisplay will display a cursor in WINDOW.
+WINDOW nil or omitted means report on the selected window.  */)
+     (window)
      Lisp_Object window;
 {
   struct window *w;
@@ -6641,37 +6639,37 @@ syms_of_display ()
   Qredisplay_dont_pause = intern ("redisplay-dont-pause");
   staticpro (&Qredisplay_dont_pause);
 
-  DEFVAR_INT ("baud-rate", &baud_rate
-    /* *The output baud rate of the terminal.
+  DEFVAR_INT ("baud-rate", &baud_rate,
+    doc: /* *The output baud rate of the terminal.
 On most systems, changing this value will affect the amount of padding
 and the other strategic decisions made during redisplay.  */);
   
-  DEFVAR_BOOL ("inverse-video", &inverse_video
-    /* *Non-nil means invert the entire frame display.
+  DEFVAR_BOOL ("inverse-video", &inverse_video,
+    doc: /* *Non-nil means invert the entire frame display.
 This means everything is in inverse video which otherwise would not be.  */);
   
-  DEFVAR_BOOL ("visible-bell", &visible_bell
-    /* *Non-nil means try to flash the frame to represent a bell.  */);
+  DEFVAR_BOOL ("visible-bell", &visible_bell,
+    doc: /* *Non-nil means try to flash the frame to represent a bell.  */);
   
-  DEFVAR_BOOL ("no-redraw-on-reenter", &no_redraw_on_reenter
-    /* *Non-nil means no need to redraw entire frame after suspending.
+  DEFVAR_BOOL ("no-redraw-on-reenter", &no_redraw_on_reenter,
+    doc: /* *Non-nil means no need to redraw entire frame after suspending.
 A non-nil value is useful if the terminal can automatically preserve
 Emacs's frame display when you reenter Emacs.
 It is up to you to set this variable if your terminal can do that.  */);
   
-  DEFVAR_LISP ("window-system", &Vwindow_system
-    /* A symbol naming the window-system under which Emacs is running
+  DEFVAR_LISP ("window-system", &Vwindow_system,
+    doc: /* A symbol naming the window-system under which Emacs is running
 \(such as `x'), or nil if emacs is running on an ordinary terminal.  */);
   
-  DEFVAR_LISP ("window-system-version", &Vwindow_system_version
-    /* The version number of the window system in use.
+  DEFVAR_LISP ("window-system-version", &Vwindow_system_version,
+    doc: /* The version number of the window system in use.
 For X windows, this is 10 or 11.  */);
   
-  DEFVAR_BOOL ("cursor-in-echo-area", &cursor_in_echo_area
-    /* Non-nil means put cursor in minibuffer, at end of any message there.  */);
+  DEFVAR_BOOL ("cursor-in-echo-area", &cursor_in_echo_area,
+    doc: /* Non-nil means put cursor in minibuffer, at end of any message there.  */);
   
-  DEFVAR_LISP ("glyph-table", &Vglyph_table
-    /* Table defining how to output a glyph code to the frame.
+  DEFVAR_LISP ("glyph-table", &Vglyph_table,
+    doc: /* Table defining how to output a glyph code to the frame.
 If not nil, this is a vector indexed by glyph code to define the glyph.
 Each element can be:
  integer: a glyph code which this glyph is an alias for.
@@ -6681,13 +6679,13 @@ Each element can be:
     while outputting it.  */);
   Vglyph_table = Qnil;
 
-  DEFVAR_LISP ("standard-display-table", &Vstandard_display_table
-    /* Display table to use for buffers that specify none.
+  DEFVAR_LISP ("standard-display-table", &Vstandard_display_table,
+    doc: /* Display table to use for buffers that specify none.
 See `buffer-display-table' for more information.  */);
   Vstandard_display_table = Qnil;
 
-  DEFVAR_BOOL ("redisplay-dont-pause", &redisplay_dont_pause
-    /* *Non-nil means update isn't paused when input is detected.  */);
+  DEFVAR_BOOL ("redisplay-dont-pause", &redisplay_dont_pause,
+    doc: /* *Non-nil means update isn't paused when input is detected.  */);
   redisplay_dont_pause = 0;
 
   /* Initialize `window-system', unless init_display already decided it.  */
diff --git a/src/editfns.c b/src/editfns.c
index af2839f4f0a..51d328ab2ec 100644
--- a/src/editfns.c
+++ b/src/editfns.c
@@ -34,7 +34,6 @@ Boston, MA 02111-1307, USA.  */
 #include <unistd.h>
 #endif
 
-#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "intervals.h"
 #include "buffer.h"
@@ -165,8 +164,8 @@ init_editfns ()
 }
 
 DEFUN ("char-to-string", Fchar_to_string, Schar_to_string, 1, 1, 0,
-       /* Convert arg CHARACTER to a string containing that character.  */
-       (character))
+       doc: /* Convert arg CHARACTER to a string containing that character.  */)
+     (character)
      Lisp_Object character;
 {
   int len;
@@ -181,9 +180,9 @@ DEFUN ("char-to-string", Fchar_to_string, Schar_to_string, 1, 1, 0,
 }
 
 DEFUN ("string-to-char", Fstring_to_char, Sstring_to_char, 1, 1, 0,
-       /* Convert arg STRING to a character, the first character of that string.
-A multibyte character is handled correctly.  */
-       (string))
+       doc: /* Convert arg STRING to a character, the first character of that string.
+A multibyte character is handled correctly.  */)
+     (string)
      register Lisp_Object string;
 {
   register Lisp_Object val;
@@ -213,9 +212,9 @@ buildmark (charpos, bytepos)
 }
 
 DEFUN ("point", Fpoint, Spoint, 0, 0, 0,
-       /* Return value of point, as an integer.
-Beginning of buffer is position (point-min).  */
-       ())
+       doc: /* Return value of point, as an integer.
+Beginning of buffer is position (point-min).  */)
+     ()
 {
   Lisp_Object temp;
   XSETFASTINT (temp, PT);
@@ -223,8 +222,8 @@ Beginning of buffer is position (point-min).  */
 }
 
 DEFUN ("point-marker", Fpoint_marker, Spoint_marker, 0, 0, 0,
-       /* Return value of point, as a marker object.  */
-       ())
+       doc: /* Return value of point, as a marker object.  */)
+     ()
 {
   return buildmark (PT, PT_BYTE);
 }
@@ -242,12 +241,12 @@ clip_to_bounds (lower, num, upper)
 }
 
 DEFUN ("goto-char", Fgoto_char, Sgoto_char, 1, 1, "NGoto char: ",
-       /* Set point to POSITION, a number or marker.
+       doc: /* Set point to POSITION, a number or marker.
 Beginning of buffer is position (point-min), end is (point-max).
 If the position is in the middle of a multibyte form,
 the actual point is set at the head of the multibyte form
-except in the case that `enable-multibyte-characters' is nil.  */
-       (position))
+except in the case that `enable-multibyte-characters' is nil.  */)
+     (position)
      register Lisp_Object position;
 {
   int pos;
@@ -300,24 +299,24 @@ region_limit (beginningp)
 }
 
 DEFUN ("region-beginning", Fregion_beginning, Sregion_beginning, 0, 0, 0,
-       /* Return position of beginning of region, as an integer.  */
-       ())
+       doc: /* Return position of beginning of region, as an integer.  */)
+     ()
 {
   return region_limit (1);
 }
 
 DEFUN ("region-end", Fregion_end, Sregion_end, 0, 0, 0,
-       /* Return position of end of region, as an integer.  */
-       ())
+       doc: /* Return position of end of region, as an integer.  */)
+     ()
 {
   return region_limit (0);
 }
 
 DEFUN ("mark-marker", Fmark_marker, Smark_marker, 0, 0, 0,
-       /* Return this buffer's mark, as a marker object.
+       doc: /* Return this buffer's mark, as a marker object.
 Watch out!  Moving this marker changes the mark position.
-If you set the marker not to point anywhere, the buffer will have no mark.  */
-       ())
+If you set the marker not to point anywhere, the buffer will have no mark.  */)
+     ()
 {
   return current_buffer->mark;
 }
@@ -557,10 +556,10 @@ find_field (pos, merge_at_boundary, beg, end)
 
 
 DEFUN ("delete-field", Fdelete_field, Sdelete_field, 0, 1, 0,
-       /* Delete the field surrounding POS.
+       doc: /* Delete the field surrounding POS.
 A field is a region of text with the same `field' property.
-If POS is nil, the value of point is used for POS.  */
-       (pos))
+If POS is nil, the value of point is used for POS.  */)
+     (pos)
      Lisp_Object pos;
 {
   int beg, end;
@@ -571,10 +570,10 @@ If POS is nil, the value of point is used for POS.  */
 }
 
 DEFUN ("field-string", Ffield_string, Sfield_string, 0, 1, 0,
-       /* Return the contents of the field surrounding POS as a string.
+       doc: /* Return the contents of the field surrounding POS as a string.
 A field is a region of text with the same `field' property.
-If POS is nil, the value of point is used for POS.  */
-       (pos))
+If POS is nil, the value of point is used for POS.  */)
+     (pos)
      Lisp_Object pos;
 {
   int beg, end;
@@ -583,10 +582,10 @@ If POS is nil, the value of point is used for POS.  */
 }
 
 DEFUN ("field-string-no-properties", Ffield_string_no_properties, Sfield_string_no_properties, 0, 1, 0,
-       /* Return the contents of the field around POS, without text-properties.
+       doc: /* Return the contents of the field around POS, without text-properties.
 A field is a region of text with the same `field' property.
-If POS is nil, the value of point is used for POS.  */
-       (pos))
+If POS is nil, the value of point is used for POS.  */)
+     (pos)
      Lisp_Object pos;
 {
   int beg, end;
@@ -595,12 +594,12 @@ If POS is nil, the value of point is used for POS.  */
 }
 
 DEFUN ("field-beginning", Ffield_beginning, Sfield_beginning, 0, 2, 0,
-       /* Return the beginning of the field surrounding POS.
+       doc: /* Return the beginning of the field surrounding POS.
 A field is a region of text with the same `field' property.
 If POS is nil, the value of point is used for POS.
 If ESCAPE-FROM-EDGE is non-nil and POS is at the beginning of its
-field, then the beginning of the *previous* field is returned.  */
-       (pos, escape_from_edge))
+field, then the beginning of the *previous* field is returned.  */)
+     (pos, escape_from_edge)
      Lisp_Object pos, escape_from_edge;
 {
   int beg;
@@ -609,12 +608,12 @@ field, then the beginning of the *previous* field is returned.  */
 }
 
 DEFUN ("field-end", Ffield_end, Sfield_end, 0, 2, 0,
-       /* Return the end of the field surrounding POS.
+       doc: /* Return the end of the field surrounding POS.
 A field is a region of text with the same `field' property.
 If POS is nil, the value of point is used for POS.
 If ESCAPE-FROM-EDGE is non-nil and POS is at the end of its field,
-then the end of the *following* field is returned.  */
-       (pos, escape_from_edge))
+then the end of the *following* field is returned.  */)
+     (pos, escape_from_edge)
      Lisp_Object pos, escape_from_edge;
 {
   int end;
@@ -623,7 +622,7 @@ then the end of the *following* field is returned.  */
 }
 
 DEFUN ("constrain-to-field", Fconstrain_to_field, Sconstrain_to_field, 2, 5, 0,
-       /* Return the position closest to NEW-POS that is in the same field as OLD-POS.
+       doc: /* Return the position closest to NEW-POS that is in the same field as OLD-POS.
 
 A field is a region of text with the same `field' property.
 If NEW-POS is nil, then the current point is used instead, and set to the
@@ -648,8 +647,8 @@ only in the case where they can still move to the right line.
 If the optional argument INHIBIT-CAPTURE-PROPERTY is non-nil, and OLD-POS has
 a non-nil property of that name, then any field boundaries are ignored.
 
-Field boundaries are not noticed if `inhibit-field-text-motion' is non-nil.  */
-  (new_pos, old_pos, escape_from_edge, only_in_line, inhibit_capture_property))
+Field boundaries are not noticed if `inhibit-field-text-motion' is non-nil.  */)
+     (new_pos, old_pos, escape_from_edge, only_in_line, inhibit_capture_property)
      Lisp_Object new_pos, old_pos;
      Lisp_Object escape_from_edge, only_in_line, inhibit_capture_property;
 {
@@ -716,7 +715,7 @@ Field boundaries are not noticed if `inhibit-field-text-motion' is non-nil.  */
 
 DEFUN ("line-beginning-position", Fline_beginning_position, Sline_beginning_position,
   0, 1, 0,
-       /* Return the character position of the first character on the current line.
+       doc: /* Return the character position of the first character on the current line.
 With argument N not nil or 1, move forward N - 1 lines first.
 If scan reaches end of buffer, return that position.
 The scan does not cross a field boundary unless it would move
@@ -724,8 +723,8 @@ beyond there to a different line.  Field boundaries are not noticed if
 `inhibit-field-text-motion' is non-nil.  And if N is nil or 1,
 and scan starts at a field boundary, the scan stops as soon as it starts.
 
-This function does not move point.  */
-       (n))
+This function does not move point.  */)
+     (n)
      Lisp_Object n;
 {
   int orig, orig_byte, end;
@@ -750,11 +749,11 @@ This function does not move point.  */
 
 DEFUN ("line-end-position", Fline_end_position, Sline_end_position,
   0, 1, 0,
-       /* Return the character position of the last character on the current line.
+       doc: /* Return the character position of the last character on the current line.
 With argument N not nil or 1, move forward N - 1 lines first.
 If scan reaches end of buffer, return that position.
-This function does not move point.  */
-       (n))
+This function does not move point.  */)
+     (n)
      Lisp_Object n;
 {
   int end_pos;
@@ -871,7 +870,7 @@ save_excursion_restore (info)
 }
 
 DEFUN ("save-excursion", Fsave_excursion, Ssave_excursion, 0, UNEVALLED, 0,
-       /* Save point, mark, and current buffer; execute BODY; restore those things.
+       doc: /* Save point, mark, and current buffer; execute BODY; restore those things.
 Executes BODY just like `progn'.
 The values of point, mark and the current buffer are restored
 even in case of abnormal exit (throw or error).
@@ -880,8 +879,8 @@ The state of activation of the mark is also restored.
 This construct does not save `deactivate-mark', and therefore
 functions that change the buffer will still cause deactivation
 of the mark at the end of the command.  To prevent that, bind
-`deactivate-mark' with `let'.  */
-       (args))
+`deactivate-mark' with `let'.  */)
+     (args)
      Lisp_Object args;
 {
   register Lisp_Object val;
@@ -894,9 +893,9 @@ of the mark at the end of the command.  To prevent that, bind
 }
 
 DEFUN ("save-current-buffer", Fsave_current_buffer, Ssave_current_buffer, 0, UNEVALLED, 0,
-       /* Save the current buffer; execute BODY; restore the current buffer.
-Executes BODY just like `progn'.  */
-       (args))
+       doc: /* Save the current buffer; execute BODY; restore the current buffer.
+Executes BODY just like `progn'.  */)
+     (args)
      Lisp_Object args;
 {
   Lisp_Object val;
@@ -909,9 +908,9 @@ Executes BODY just like `progn'.  */
 }
 
 DEFUN ("buffer-size", Fbufsize, Sbufsize, 0, 1, 0,
-       /* Return the number of characters in the current buffer.
-If BUFFER, return the number of characters in that buffer instead.  */
-       (buffer))
+       doc: /* Return the number of characters in the current buffer.
+If BUFFER, return the number of characters in that buffer instead.  */)
+     (buffer)
      Lisp_Object buffer;
 {
   if (NILP (buffer))
@@ -925,9 +924,9 @@ If BUFFER, return the number of characters in that buffer instead.  */
 }
 
 DEFUN ("point-min", Fpoint_min, Spoint_min, 0, 0, 0,
-       /* Return the minimum permissible value of point in the current buffer.
-This is 1, unless narrowing (a buffer restriction) is in effect.  */
-       ())
+       doc: /* Return the minimum permissible value of point in the current buffer.
+This is 1, unless narrowing (a buffer restriction) is in effect.  */)
+     ()
 {
   Lisp_Object temp;
   XSETFASTINT (temp, BEGV);
@@ -935,18 +934,18 @@ This is 1, unless narrowing (a buffer restriction) is in effect.  */
 }
 
 DEFUN ("point-min-marker", Fpoint_min_marker, Spoint_min_marker, 0, 0, 0,
-       /* Return a marker to the minimum permissible value of point in this buffer.
-This is the beginning, unless narrowing (a buffer restriction) is in effect.  */
-       ())
+       doc: /* Return a marker to the minimum permissible value of point in this buffer.
+This is the beginning, unless narrowing (a buffer restriction) is in effect.  */)
+     ()
 {
   return buildmark (BEGV, BEGV_BYTE);
 }
 
 DEFUN ("point-max", Fpoint_max, Spoint_max, 0, 0, 0,
-       /* Return the maximum permissible value of point in the current buffer.
+       doc: /* Return the maximum permissible value of point in the current buffer.
 This is (1+ (buffer-size)), unless narrowing (a buffer restriction)
-is in effect, in which case it is less.  */
-       ())
+is in effect, in which case it is less.  */)
+     ()
 {
   Lisp_Object temp;
   XSETFASTINT (temp, ZV);
@@ -954,18 +953,18 @@ is in effect, in which case it is less.  */
 }
 
 DEFUN ("point-max-marker", Fpoint_max_marker, Spoint_max_marker, 0, 0, 0,
-       /* Return a marker to the maximum permissible value of point in this buffer.
+       doc: /* Return a marker to the maximum permissible value of point in this buffer.
 This is (1+ (buffer-size)), unless narrowing (a buffer restriction)
-is in effect, in which case it is less.  */
-       ())
+is in effect, in which case it is less.  */)
+     ()
 {
   return buildmark (ZV, ZV_BYTE);
 }
 
 DEFUN ("gap-position", Fgap_position, Sgap_position, 0, 0, 0,
-       /* Return the position of the gap, in the current buffer.
-See also `gap-size'.  */
-       ())
+       doc: /* Return the position of the gap, in the current buffer.
+See also `gap-size'.  */)
+     ()
 {
   Lisp_Object temp;
   XSETFASTINT (temp, GPT);
@@ -973,9 +972,9 @@ See also `gap-size'.  */
 }
 
 DEFUN ("gap-size", Fgap_size, Sgap_size, 0, 0, 0,
-       /* Return the size of the current buffer's gap.
-See also `gap-position'.  */
-       ())
+       doc: /* Return the size of the current buffer's gap.
+See also `gap-position'.  */)
+     ()
 {
   Lisp_Object temp;
   XSETFASTINT (temp, GAP_SIZE);
@@ -983,9 +982,9 @@ See also `gap-position'.  */
 }
 
 DEFUN ("position-bytes", Fposition_bytes, Sposition_bytes, 1, 1, 0,
-       /* Return the byte position for character position POSITION.
-If POSITION is out of range, the value is nil.  */
-       (position))
+       doc: /* Return the byte position for character position POSITION.
+If POSITION is out of range, the value is nil.  */)
+     (position)
      Lisp_Object position;
 {
   CHECK_NUMBER_COERCE_MARKER (position, 1);
@@ -995,9 +994,9 @@ If POSITION is out of range, the value is nil.  */
 }
 
 DEFUN ("byte-to-position", Fbyte_to_position, Sbyte_to_position, 1, 1, 0,
-       /* Return the character position for byte position BYTEPOS.
-If BYTEPOS is out of range, the value is nil.  */
-       (bytepos))
+       doc: /* Return the character position for byte position BYTEPOS.
+If BYTEPOS is out of range, the value is nil.  */)
+     (bytepos)
      Lisp_Object bytepos;
 {
   CHECK_NUMBER (bytepos, 1);
@@ -1007,9 +1006,9 @@ If BYTEPOS is out of range, the value is nil.  */
 }
 
 DEFUN ("following-char", Ffollowing_char, Sfollowing_char, 0, 0, 0,
-       /* Return the character following point, as a number.
-At the end of the buffer or accessible region, return 0.  */
-       ())
+       doc: /* Return the character following point, as a number.
+At the end of the buffer or accessible region, return 0.  */)
+     ()
 {
   Lisp_Object temp;
   if (PT >= ZV)
@@ -1020,9 +1019,9 @@ At the end of the buffer or accessible region, return 0.  */
 }
 
 DEFUN ("preceding-char", Fprevious_char, Sprevious_char, 0, 0, 0,
-       /* Return the character preceding point, as a number.
-At the beginning of the buffer or accessible region, return 0.  */
-       ())
+       doc: /* Return the character preceding point, as a number.
+At the beginning of the buffer or accessible region, return 0.  */)
+     ()
 {
   Lisp_Object temp;
   if (PT <= BEGV)
@@ -1039,9 +1038,9 @@ At the beginning of the buffer or accessible region, return 0.  */
 }
 
 DEFUN ("bobp", Fbobp, Sbobp, 0, 0, 0,
-       /* Return t if point is at the beginning of the buffer.
-If the buffer is narrowed, this means the beginning of the narrowed part.  */
-       ())
+       doc: /* Return t if point is at the beginning of the buffer.
+If the buffer is narrowed, this means the beginning of the narrowed part.  */)
+     ()
 {
   if (PT == BEGV)
     return Qt;
@@ -1049,9 +1048,9 @@ If the buffer is narrowed, this means the beginning of the narrowed part.  */
 }
 
 DEFUN ("eobp", Feobp, Seobp, 0, 0, 0,
-       /* Return t if point is at the end of the buffer.
-If the buffer is narrowed, this means the end of the narrowed part.  */
-       ())
+       doc: /* Return t if point is at the end of the buffer.
+If the buffer is narrowed, this means the end of the narrowed part.  */)
+     ()
 {
   if (PT == ZV)
     return Qt;
@@ -1059,8 +1058,8 @@ If the buffer is narrowed, this means the end of the narrowed part.  */
 }
 
 DEFUN ("bolp", Fbolp, Sbolp, 0, 0, 0,
-       /* Return t if point is at the beginning of a line.  */
-       ())
+       doc: /* Return t if point is at the beginning of a line.  */)
+     ()
 {
   if (PT == BEGV || FETCH_BYTE (PT_BYTE - 1) == '\n')
     return Qt;
@@ -1068,9 +1067,9 @@ DEFUN ("bolp", Fbolp, Sbolp, 0, 0, 0,
 }
 
 DEFUN ("eolp", Feolp, Seolp, 0, 0, 0,
-       /* Return t if point is at the end of a line.
-`End of a line' includes point being at the end of the buffer.  */
-       ())
+       doc: /* Return t if point is at the end of a line.
+`End of a line' includes point being at the end of the buffer.  */)
+     ()
 {
   if (PT == ZV || FETCH_BYTE (PT_BYTE) == '\n')
     return Qt;
@@ -1078,10 +1077,10 @@ DEFUN ("eolp", Feolp, Seolp, 0, 0, 0,
 }
 
 DEFUN ("char-after", Fchar_after, Schar_after, 0, 1, 0,
-       /* Return character in current buffer at position POS.
+       doc: /* Return character in current buffer at position POS.
 POS is an integer or a marker.
-If POS is out of range, the value is nil.  */
-       (pos))
+If POS is out of range, the value is nil.  */)
+     (pos)
      Lisp_Object pos;
 {
   register int pos_byte;
@@ -1111,10 +1110,10 @@ If POS is out of range, the value is nil.  */
 }
 
 DEFUN ("char-before", Fchar_before, Schar_before, 0, 1, 0,
-       /* Return character in current buffer preceding position POS.
+       doc: /* Return character in current buffer preceding position POS.
 POS is an integer or a marker.
-If POS is out of range, the value is nil.  */
-       (pos))
+If POS is out of range, the value is nil.  */)
+     (pos)
      Lisp_Object pos;
 {
   register Lisp_Object val;
@@ -1157,14 +1156,14 @@ If POS is out of range, the value is nil.  */
 }
 
 DEFUN ("user-login-name", Fuser_login_name, Suser_login_name, 0, 1, 0,
-       /* Return the name under which the user logged in, as a string.
+       doc: /* Return the name under which the user logged in, as a string.
 This is based on the effective uid, not the real uid.
 Also, if the environment variable LOGNAME or USER is set,
 that determines the value of this function.
 
 If optional argument UID is an integer, return the login name of the user
-with that uid, or nil if there is no such user.  */
-       (uid))
+with that uid, or nil if there is no such user.  */)
+     (uid)
      Lisp_Object uid;
 {
   struct passwd *pw;
@@ -1185,10 +1184,10 @@ with that uid, or nil if there is no such user.  */
 
 DEFUN ("user-real-login-name", Fuser_real_login_name, Suser_real_login_name,
   0, 0, 0,
-       /* Return the name of the user's real uid, as a string.
+       doc: /* Return the name of the user's real uid, as a string.
 This ignores the environment variables LOGNAME and USER, so it differs from
-`user-login-name' when running under `su'.  */
-       ())
+`user-login-name' when running under `su'.  */)
+     ()
 {
   /* Set up the user name info if we didn't do it before.
      (That can happen if Emacs is dumpable
@@ -1199,31 +1198,31 @@ This ignores the environment variables LOGNAME and USER, so it differs from
 }
 
 DEFUN ("user-uid", Fuser_uid, Suser_uid, 0, 0, 0,
-       /* Return the effective uid of Emacs.
-Value is an integer or float, depending on the value.  */
-       ())
+       doc: /* Return the effective uid of Emacs.
+Value is an integer or float, depending on the value.  */)
+     ()
 {
   return make_fixnum_or_float (geteuid ());
 }
 
 DEFUN ("user-real-uid", Fuser_real_uid, Suser_real_uid, 0, 0, 0,
-       /* Return the real uid of Emacs.
-Value is an integer or float, depending on the value.  */
-       ())
+       doc: /* Return the real uid of Emacs.
+Value is an integer or float, depending on the value.  */)
+     ()
 {
   return make_fixnum_or_float (getuid ());
 }
 
 DEFUN ("user-full-name", Fuser_full_name, Suser_full_name, 0, 1, 0,
-       /* Return the full name of the user logged in, as a string.
+       doc: /* Return the full name of the user logged in, as a string.
 If the full name corresponding to Emacs's userid is not known,
 return "unknown".
 
 If optional argument UID is an integer or float, return the full name
 of the user with that uid, or nil if there is no such user.
 If UID is a string, return the full name of the user with that login
-name, or nil if there is no such user.  */
-       (uid))
+name, or nil if there is no such user.  */)
+     (uid)
      Lisp_Object uid;
 {
   struct passwd *pw;
@@ -1271,8 +1270,8 @@ name, or nil if there is no such user.  */
 }
 
 DEFUN ("system-name", Fsystem_name, Ssystem_name, 0, 0, 0,
-       /* Return the name of the machine you are running on, as a string.  */
-       ())
+       doc: /* Return the name of the machine you are running on, as a string.  */)
+     ()
 {
   return Vsystem_name;
 }
@@ -1289,22 +1288,22 @@ get_system_name ()
 }
 
 DEFUN ("emacs-pid", Femacs_pid, Semacs_pid, 0, 0, 0,
-       /* Return the process ID of Emacs, as an integer.  */
-       ())
+       doc: /* Return the process ID of Emacs, as an integer.  */)
+     ()
 {
   return make_number (getpid ());
 }
 
 DEFUN ("current-time", Fcurrent_time, Scurrent_time, 0, 0, 0,
-       /* Return the current time, as the number of seconds since 1970-01-01 00:00:00.
+       doc: /* Return the current time, as the number of seconds since 1970-01-01 00:00:00.
 The time is returned as a list of three integers.  The first has the
 most significant 16 bits of the seconds, while the second has the
 least significant 16 bits.  The third integer gives the microsecond
 count.
 
 The microsecond count is zero on systems that do not provide
-resolution finer than a second.  */
-       ())
+resolution finer than a second.  */)
+     ()
 {
   EMACS_TIME t;
   Lisp_Object result[3];
@@ -1370,7 +1369,7 @@ lisp_time_argument (specified_time, result, usec)
 }
 
 DEFUN ("float-time", Ffloat_time, Sfloat_time, 0, 1, 0,
-       /* Return the current time, as a float number of seconds since the epoch.
+       doc: /* Return the current time, as a float number of seconds since the epoch.
 If an argument is given, it specifies a time to convert to float
 instead of the current time.  The argument should have the forms:
  (HIGH . LOW) or (HIGH LOW USEC) or (HIGH LOW . USEC).
@@ -1378,8 +1377,8 @@ Thus, you can use times obtained from `current-time'
 and from `file-attributes'.
 
 WARNING: Since the result is floating point, it may not be exact.
-Do not use this function if precise time stamps are required.  */
-       (specified_time))
+Do not use this function if precise time stamps are required.  */)
+     (specified_time)
      Lisp_Object specified_time;
 {
   time_t sec;
@@ -1446,7 +1445,7 @@ emacs_memftimeu (s, maxsize, format, format_len, tp, ut)
 }
 
 DEFUN ("format-time-string", Fformat_time_string, Sformat_time_string, 1, 3, 0,
-       /* Use FORMAT-STRING to format the time TIME, or now if omitted.
+       doc: /* Use FORMAT-STRING to format the time TIME, or now if omitted.
 TIME is specified as (HIGH LOW . IGNORED) or (HIGH . LOW), as returned by
 `current-time' or `file-attributes'.
 The third, optional, argument UNIVERSAL, if non-nil, means describe TIME
@@ -1494,8 +1493,8 @@ The modifiers are `E' and `O'.  For certain characters X,
 %EX is a locale's alternative version of %X;
 %OX is like %X, but uses the locale's number symbols.
 
-For example, to produce full ISO 8601 format, use "%Y-%m-%dT%T%z".  */
-       (format_string, time, universal))
+For example, to produce full ISO 8601 format, use "%Y-%m-%dT%T%z".  */)
+     (format_string, time, universal)
      Lisp_Object format_string, time, universal;
 {
   time_t value;
@@ -1543,7 +1542,7 @@ For example, to produce full ISO 8601 format, use "%Y-%m-%dT%T%z".  */
 }
 
 DEFUN ("decode-time", Fdecode_time, Sdecode_time, 0, 1, 0,
-       /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST ZONE).
+       doc: /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST ZONE).
 The optional SPECIFIED-TIME should be a list of (HIGH LOW . IGNORED)
 or (HIGH . LOW), as from `current-time' and `file-attributes', or `nil'
 to use the current time.  The list has the following nine members:
@@ -1554,8 +1553,8 @@ MONTH is an integer between 1 and 12.  YEAR is an integer indicating the
 four-digit year.  DOW is the day of week, an integer between 0 and 6, where
 0 is Sunday.  DST is t if daylight savings time is effect, otherwise nil.
 ZONE is an integer indicating the number of seconds east of Greenwich.
-(Note that Common Lisp has different meanings for DOW and ZONE.)  */
-  (specified_time))
+(Note that Common Lisp has different meanings for DOW and ZONE.)  */)
+     (specified_time)
      Lisp_Object specified_time;
 {
   time_t time_spec;
@@ -1589,7 +1588,7 @@ ZONE is an integer indicating the number of seconds east of Greenwich.
 }
 
 DEFUN ("encode-time", Fencode_time, Sencode_time, 6, MANY, 0,
-       /* Convert SECOND, MINUTE, HOUR, DAY, MONTH, YEAR and ZONE to internal time.
+       doc: /* Convert SECOND, MINUTE, HOUR, DAY, MONTH, YEAR and ZONE to internal time.
 This is the reverse operation of `decode-time', which see.
 ZONE defaults to the current time zone rule.  This can
 be a string or t (as from `set-time-zone-rule'), or it can be a list
@@ -1604,8 +1603,8 @@ This feature lets (apply 'encode-time (decode-time ...)) work.
 Out-of-range values for SEC, MINUTE, HOUR, DAY, or MONTH are allowed;
 for example, a DAY of 0 means the day preceding the given month.
 Year numbers less than 100 are treated just like other year numbers.
-If you want them to stand for years in this century, you must do that yourself.  */
-       (nargs, args))
+If you want them to stand for years in this century, you must do that yourself.  */)
+     (nargs, args)
      int nargs;
      register Lisp_Object *args;
 {
@@ -1674,7 +1673,7 @@ If you want them to stand for years in this century, you must do that yourself.
 }
 
 DEFUN ("current-time-string", Fcurrent_time_string, Scurrent_time_string, 0, 1, 0,
-       /* Return the current time, as a human-readable string.
+       doc: /* Return the current time, as a human-readable string.
 Programs can use this function to decode a time,
 since the number of columns in each field is fixed.
 The format is `Sun Sep 16 01:03:52 1973'.
@@ -1687,8 +1686,8 @@ instead of the current time.  The argument should have the form:
 or the form:
   (HIGH LOW . IGNORED).
 Thus, you can use times obtained from `current-time'
-and from `file-attributes'.  */
-       (specified_time))
+and from `file-attributes'.  */)
+     (specified_time)
      Lisp_Object specified_time;
 {
   time_t value;
@@ -1732,7 +1731,7 @@ tm_diff (a, b)
 }
 
 DEFUN ("current-time-zone", Fcurrent_time_zone, Scurrent_time_zone, 0, 1, 0,
-       /* Return the offset and name for the local time zone.
+       doc: /* Return the offset and name for the local time zone.
 This returns a list of the form (OFFSET NAME).
 OFFSET is an integer number of seconds ahead of UTC (east of Greenwich).
     A negative value means west of Greenwich.
@@ -1747,8 +1746,8 @@ and from `file-attributes'.
 
 Some operating systems cannot provide all this information to Emacs;
 in this case, `current-time-zone' returns a list containing nil for
-the data it can't find.  */
-       (specified_time))
+the data it can't find.  */)
+     (specified_time)
      Lisp_Object specified_time;
 {
   time_t value;
@@ -1804,10 +1803,10 @@ the data it can't find.  */
 static char **environbuf;
 
 DEFUN ("set-time-zone-rule", Fset_time_zone_rule, Sset_time_zone_rule, 1, 1, 0,
-       /* Set the local time zone using TZ, a string specifying a time zone rule.
+       doc: /* Set the local time zone using TZ, a string specifying a time zone rule.
 If TZ is nil, use implementation-defined default time zone information.
-If TZ is t, use Universal Time.  */
-       (tz))
+If TZ is t, use Universal Time.  */)
+     (tz)
      Lisp_Object tz;
 {
   char *tzstring;
@@ -1991,7 +1990,7 @@ insert1 (arg)
    we don't care if it gets trashed.  */
 
 DEFUN ("insert", Finsert, Sinsert, 0, MANY, 0,
-       /* Insert the arguments, either strings or characters, at point.
+       doc: /* Insert the arguments, either strings or characters, at point.
 Point and before-insertion markers move forward to end up
  after the inserted text.
 Any other markers at the point of insertion remain before the text.
@@ -1999,8 +1998,8 @@ Any other markers at the point of insertion remain before the text.
 If the current buffer is multibyte, unibyte strings are converted
 to multibyte for insertion (see `unibyte-char-to-multibyte').
 If the current buffer is unibyte, multibyte strings are converted
-to unibyte for insertion.  */
-       (nargs, args))
+to unibyte for insertion.  */)
+     (nargs, args)
      int nargs;
      register Lisp_Object *args;
 {
@@ -2010,7 +2009,7 @@ to unibyte for insertion.  */
 
 DEFUN ("insert-and-inherit", Finsert_and_inherit, Sinsert_and_inherit,
    0, MANY, 0,
-       /* Insert the arguments at point, inheriting properties from adjoining text.
+       doc: /* Insert the arguments at point, inheriting properties from adjoining text.
 Point and before-insertion markers move forward to end up
  after the inserted text.
 Any other markers at the point of insertion remain before the text.
@@ -2018,8 +2017,8 @@ Any other markers at the point of insertion remain before the text.
 If the current buffer is multibyte, unibyte strings are converted
 to multibyte for insertion (see `unibyte-char-to-multibyte').
 If the current buffer is unibyte, multibyte strings are converted
-to unibyte for insertion.  */
-       (nargs, args))
+to unibyte for insertion.  */)
+     (nargs, args)
      int nargs;
      register Lisp_Object *args;
 {
@@ -2029,14 +2028,14 @@ to unibyte for insertion.  */
 }
 
 DEFUN ("insert-before-markers", Finsert_before_markers, Sinsert_before_markers, 0, MANY, 0,
-       /* Insert strings or characters at point, relocating markers after the text.
+       doc: /* Insert strings or characters at point, relocating markers after the text.
 Point and markers move forward to end up after the inserted text.
 
 If the current buffer is multibyte, unibyte strings are converted
 to multibyte for insertion (see `unibyte-char-to-multibyte').
 If the current buffer is unibyte, multibyte strings are converted
-to unibyte for insertion.  */
-       (nargs, args))
+to unibyte for insertion.  */)
+     (nargs, args)
      int nargs;
      register Lisp_Object *args;
 {
@@ -2048,14 +2047,14 @@ to unibyte for insertion.  */
 
 DEFUN ("insert-before-markers-and-inherit", Finsert_and_inherit_before_markers,
   Sinsert_and_inherit_before_markers, 0, MANY, 0,
-       /* Insert text at point, relocating markers and inheriting properties.
+       doc: /* Insert text at point, relocating markers and inheriting properties.
 Point and markers move forward to end up after the inserted text.
 
 If the current buffer is multibyte, unibyte strings are converted
 to multibyte for insertion (see `unibyte-char-to-multibyte').
 If the current buffer is unibyte, multibyte strings are converted
-to unibyte for insertion.  */
-       (nargs, args))
+to unibyte for insertion.  */)
+     (nargs, args)
      int nargs;
      register Lisp_Object *args;
 {
@@ -2066,12 +2065,12 @@ to unibyte for insertion.  */
 }
 
 DEFUN ("insert-char", Finsert_char, Sinsert_char, 2, 3, 0,
-       /* Insert COUNT (second arg) copies of CHARACTER (first arg).
+       doc: /* Insert COUNT (second arg) copies of CHARACTER (first arg).
 Both arguments are required.
 Point, and before-insertion markers, are relocated as in the function `insert'.
 The optional third arg INHERIT, if non-nil, says to inherit text properties
-from adjoining text, if those properties are sticky.  */
-       (character, count, inherit))
+from adjoining text, if those properties are sticky.  */)
+     (character, count, inherit)
        Lisp_Object character, count, inherit;
 {
   register unsigned char *string;
@@ -2222,15 +2221,15 @@ update_buffer_properties (start, end)
 }
 
 DEFUN ("buffer-substring", Fbuffer_substring, Sbuffer_substring, 2, 2, 0,
-       /* Return the contents of part of the current buffer as a string.
+       doc: /* Return the contents of part of the current buffer as a string.
 The two arguments START and END are character positions;
 they can be in either order.
 The string returned is multibyte if the buffer is multibyte.
 
 This function copies the text properties of that part of the buffer
 into the result string; if you don't want the text properties,
-use `buffer-substring-no-properties' instead.  */
-       (start, end))
+use `buffer-substring-no-properties' instead.  */)
+     (start, end)
      Lisp_Object start, end;
 {
   register int b, e;
@@ -2244,10 +2243,10 @@ use `buffer-substring-no-properties' instead.  */
 
 DEFUN ("buffer-substring-no-properties", Fbuffer_substring_no_properties,
        Sbuffer_substring_no_properties, 2, 2, 0,
-       /* Return the characters of part of the buffer, without the text properties.
+       doc: /* Return the characters of part of the buffer, without the text properties.
 The two arguments START and END are character positions;
-they can be in either order.  */
-       (start, end))
+they can be in either order.  */)
+     (start, end)
      Lisp_Object start, end;
 {
   register int b, e;
@@ -2260,21 +2259,21 @@ they can be in either order.  */
 }
 
 DEFUN ("buffer-string", Fbuffer_string, Sbuffer_string, 0, 0, 0,
-       /* Return the contents of the current buffer as a string.
+       doc: /* Return the contents of the current buffer as a string.
 If narrowing is in effect, this function returns only the visible part
-of the buffer.  */
-       ())
+of the buffer.  */)
+     ()
 {
   return make_buffer_string (BEGV, ZV, 1);
 }
 
 DEFUN ("insert-buffer-substring", Finsert_buffer_substring, Sinsert_buffer_substring,
   1, 3, 0,
-       /* Insert before point a substring of the contents of buffer BUFFER.
+       doc: /* Insert before point a substring of the contents of buffer BUFFER.
 BUFFER may be a buffer or a buffer name.
 Arguments START and END are character numbers specifying the substring.
-They default to the beginning and the end of BUFFER.  */
-       (buf, start, end))
+They default to the beginning and the end of BUFFER.  */)
+     (buf, start, end)
      Lisp_Object buf, start, end;
 {
   register int b, e, temp;
@@ -2320,15 +2319,15 @@ They default to the beginning and the end of BUFFER.  */
 
 DEFUN ("compare-buffer-substrings", Fcompare_buffer_substrings, Scompare_buffer_substrings,
   6, 6, 0,
-       /* Compare two substrings of two buffers; return result as number.
+       doc: /* Compare two substrings of two buffers; return result as number.
 the value is -N if first string is less after N-1 chars,
 +N if first string is greater after N-1 chars, or 0 if strings match.
 Each substring is represented as three arguments: BUFFER, START and END.
 That makes six args in all, three for each substring.
 
 The value of `case-fold-search' in the current buffer
-determines whether case is significant or ignored.  */
-       (buffer1, start1, end1, buffer2, start2, end2))
+determines whether case is significant or ignored.  */)
+     (buffer1, start1, end1, buffer2, start2, end2)
      Lisp_Object buffer1, start1, end1, buffer2, start2, end2;
 {
   register int begp1, endp1, begp2, endp2, temp;
@@ -2492,11 +2491,11 @@ subst_char_in_region_unwind_1 (arg)
 
 DEFUN ("subst-char-in-region", Fsubst_char_in_region,
   Ssubst_char_in_region, 4, 5, 0,
-       /* From START to END, replace FROMCHAR with TOCHAR each time it occurs.
+       doc: /* From START to END, replace FROMCHAR with TOCHAR each time it occurs.
 If optional arg NOUNDO is non-nil, don't record this change for undo
 and don't mark the buffer as really changed.
-Both characters must have the same length of multi-byte form.  */
-       (start, end, fromchar, tochar, noundo))
+Both characters must have the same length of multi-byte form.  */)
+     (start, end, fromchar, tochar, noundo)
      Lisp_Object start, end, fromchar, tochar, noundo;
 {
   register int pos, pos_byte, stop, i, len, end_byte;
@@ -2659,12 +2658,12 @@ Both characters must have the same length of multi-byte form.  */
 }
 
 DEFUN ("translate-region", Ftranslate_region, Stranslate_region, 3, 3, 0,
-       /* From START to END, translate characters according to TABLE.
+       doc: /* From START to END, translate characters according to TABLE.
 TABLE is a string; the Nth character in it is the mapping
 for the character with code N.
 This function does not alter multibyte characters.
-It returns the number of characters changed.  */
-       (start, end, table))
+It returns the number of characters changed.  */)
+     (start, end, table)
      Lisp_Object start;
      Lisp_Object end;
      register Lisp_Object table;
@@ -2748,10 +2747,10 @@ It returns the number of characters changed.  */
 }
 
 DEFUN ("delete-region", Fdelete_region, Sdelete_region, 2, 2, "r",
-       /* Delete the text between point and mark.
+       doc: /* Delete the text between point and mark.
 When called from a program, expects two arguments,
-positions (integers or markers) specifying the stretch to be deleted.  */
-       (start, end))
+positions (integers or markers) specifying the stretch to be deleted.  */)
+     (start, end)
      Lisp_Object start, end;
 {
   validate_region (&start, &end);
@@ -2761,8 +2760,8 @@ positions (integers or markers) specifying the stretch to be deleted.  */
 
 DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
        Sdelete_and_extract_region, 2, 2, 0,
-       /* Delete the text between START and END and return it.  */
-       (start, end))
+       doc: /* Delete the text between START and END and return it.  */)
+     (start, end)
      Lisp_Object start, end;
 {
   validate_region (&start, &end);
@@ -2770,9 +2769,9 @@ DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
 }
 
 DEFUN ("widen", Fwiden, Swiden, 0, 0, "",
-       /* Remove restrictions (narrowing) from current buffer.
-This allows the buffer's full text to be seen and edited.  */
-       ())
+       doc: /* Remove restrictions (narrowing) from current buffer.
+This allows the buffer's full text to be seen and edited.  */)
+     ()
 {
   if (BEG != BEGV || Z != ZV)
     current_buffer->clip_changed = 1;
@@ -2785,15 +2784,15 @@ This allows the buffer's full text to be seen and edited.  */
 }
 
 DEFUN ("narrow-to-region", Fnarrow_to_region, Snarrow_to_region, 2, 2, "r",
-       /* Restrict editing in this buffer to the current region.
+       doc: /* Restrict editing in this buffer to the current region.
 The rest of the text becomes temporarily invisible and untouchable
 but is not deleted; if you save the buffer in a file, the invisible
 text is included in the file.  \\[widen] makes all visible again.
 See also `save-restriction'.
 
 When calling from a program, pass two arguments; positions (integers
-or markers) bounding the text that should remain visible.  */
-       (start, end))
+or markers) bounding the text that should remain visible.  */)
+     (start, end)
      register Lisp_Object start, end;
 {
   CHECK_NUMBER_COERCE_MARKER (start, 0);
@@ -2895,7 +2894,7 @@ save_restriction_restore (data)
 }
 
 DEFUN ("save-restriction", Fsave_restriction, Ssave_restriction, 0, UNEVALLED, 0,
-       /* Execute BODY, saving and restoring current buffer's restrictions.
+       doc: /* Execute BODY, saving and restoring current buffer's restrictions.
 The buffer's restrictions make parts of the beginning and end invisible.
 (They are set up with `narrow-to-region' and eliminated with `widen'.)
 This special form, `save-restriction', saves the current buffer's restrictions
@@ -2908,8 +2907,8 @@ The value returned is the value of the last form in BODY.
 
 Note: if you are using both `save-excursion' and `save-restriction',
 use `save-excursion' outermost:
-    (save-excursion (save-restriction ...))  */
-       (body))
+    (save-excursion (save-restriction ...))  */)
+     (body)
      Lisp_Object body;
 {
   register Lisp_Object val;
@@ -2927,13 +2926,13 @@ static char *message_text;
 static int message_length;
 
 DEFUN ("message", Fmessage, Smessage, 1, MANY, 0,
-       /* Print a one-line message at the bottom of the screen.
+       doc: /* Print a one-line message at the bottom of the screen.
 The first argument is a format control string, and the rest are data
 to be formatted under control of the string.  See `format' for details.
 
 If the first argument is nil, clear any existing message; let the
-minibuffer contents show.  */
-       (nargs, args))
+minibuffer contents show.  */)
+     (nargs, args)
      int nargs;
      Lisp_Object *args;
 {
@@ -2952,14 +2951,14 @@ minibuffer contents show.  */
 }
 
 DEFUN ("message-box", Fmessage_box, Smessage_box, 1, MANY, 0,
-       /* Display a message, in a dialog box if possible.
+       doc: /* Display a message, in a dialog box if possible.
 If a dialog box is not available, use the echo area.
 The first argument is a format control string, and the rest are data
 to be formatted under control of the string.  See `format' for details.
 
 If the first argument is nil, clear any existing message; let the
-minibuffer contents show.  */
-       (nargs, args))
+minibuffer contents show.  */)
+     (nargs, args)
      int nargs;
      Lisp_Object *args;
 {
@@ -3010,7 +3009,7 @@ extern Lisp_Object last_nonmenu_event;
 #endif
 
 DEFUN ("message-or-box", Fmessage_or_box, Smessage_or_box, 1, MANY, 0,
-       /* Display a message in a dialog box or in the echo area.
+       doc: /* Display a message in a dialog box or in the echo area.
 If this command was invoked with the mouse, use a dialog box if
 `use-dialog-box' is non-nil.
 Otherwise, use the echo area.
@@ -3018,8 +3017,8 @@ The first argument is a format control string, and the rest are data
 to be formatted under control of the string.  See `format' for details.
 
 If the first argument is nil, clear any existing message; let the
-minibuffer contents show.  */
-       (nargs, args))
+minibuffer contents show.  */)
+     (nargs, args)
      int nargs;
      Lisp_Object *args;
 {
@@ -3032,19 +3031,19 @@ minibuffer contents show.  */
 }
 
 DEFUN ("current-message", Fcurrent_message, Scurrent_message, 0, 0, 0,
-       /* Return the string currently displayed in the echo area, or nil if none.  */
-       ())
+       doc: /* Return the string currently displayed in the echo area, or nil if none.  */)
+     ()
 {
   return current_message ();
 }
 
 
 DEFUN ("propertize", Fpropertize, Spropertize, 3, MANY, 0,
-       /* Return a copy of STRING with text properties added.
+       doc: /* Return a copy of STRING with text properties added.
 First argument is the string to copy.
 Remaining arguments form a sequence of PROPERTY VALUE pairs for text
-properties to add to the result.  */
-       (nargs, args))
+properties to add to the result.  */)
+     (nargs, args)
      int nargs;
      Lisp_Object *args;
 {
@@ -3086,7 +3085,7 @@ properties to add to the result.  */
    : STRING_BYTES (XSTRING (STRING)))
 
 DEFUN ("format", Fformat, Sformat, 1, MANY, 0,
-       /* Format a string out of a control-string and arguments.
+       doc: /* Format a string out of a control-string and arguments.
 The first argument is a control string.
 The other arguments are substituted into it to make the result, a string.
 It may contain %-sequences meaning to substitute the next argument.
@@ -3100,8 +3099,8 @@ It may contain %-sequences meaning to substitute the next argument.
 %c means print a number as a single character.
 %S means print any object as an s-expression (using `prin1').
   The argument used for %d, %o, %x, %e, %f, %g or %c must be a number.
-Use %% to put a single % into the output.  */
-       (nargs, args))
+Use %% to put a single % into the output.  */)
+     (nargs, args)
      int nargs;
      register Lisp_Object *args;
 {
@@ -3525,10 +3524,10 @@ format1 (string1)
 }
 
 DEFUN ("char-equal", Fchar_equal, Schar_equal, 2, 2, 0,
-       /* Return t if two characters match, optionally ignoring case.
+       doc: /* Return t if two characters match, optionally ignoring case.
 Both arguments must be characters (i.e. integers).
-Case is ignored if `case-fold-search' is non-nil in the current buffer.  */
-       (c1, c2))
+Case is ignored if `case-fold-search' is non-nil in the current buffer.  */)
+     (c1, c2)
      register Lisp_Object c1, c2;
 {
   int i1, i2;
@@ -3634,15 +3633,15 @@ transpose_markers (start1, end1, start2, end2,
 }
 
 DEFUN ("transpose-regions", Ftranspose_regions, Stranspose_regions, 4, 5, 0,
-       /* Transpose region START1 to END1 with START2 to END2.
+       doc: /* Transpose region START1 to END1 with START2 to END2.
 The regions may not be overlapping, because the size of the buffer is
 never changed in a transposition.
 
 Optional fifth arg LEAVE_MARKERS, if non-nil, means don't update
 any markers that happen to be located in the regions.
 
-Transposing beyond buffer boundaries is an error.  */
-       (startr1, endr1, startr2, endr2, leave_markers))
+Transposing beyond buffer boundaries is an error.  */)
+     (startr1, endr1, startr2, endr2, leave_markers)
      Lisp_Object startr1, endr1, startr2, endr2, leave_markers;
 {
   register int start1, end1, start2, end2;
@@ -3932,13 +3931,13 @@ syms_of_editfns ()
     = intern ("buffer-access-fontify-functions");
   staticpro (&Qbuffer_access_fontify_functions);
 
-  DEFVAR_LISP ("inhibit-field-text-motion", &Vinhibit_field_text_motion
-               /* Non-nil means.text motion commands don't notice fields.  */);
+  DEFVAR_LISP ("inhibit-field-text-motion", &Vinhibit_field_text_motion,
+               doc: /* Non-nil means.text motion commands don't notice fields.  */);
   Vinhibit_field_text_motion = Qnil;
 
   DEFVAR_LISP ("buffer-access-fontify-functions",
-               &Vbuffer_access_fontify_functions
-               /* List of functions called by `buffer-substring' to fontify if necessary.
+               &Vbuffer_access_fontify_functions,
+               doc: /* List of functions called by `buffer-substring' to fontify if necessary.
 Each function is called with two arguments which specify the range
 of the buffer being accessed.  */);
   Vbuffer_access_fontify_functions = Qnil;
@@ -3956,23 +3955,23 @@ of the buffer being accessed.  */);
   }
 
   DEFVAR_LISP ("buffer-access-fontified-property",
-               &Vbuffer_access_fontified_property
-               /* Property which (if non-nil) indicates text has been fontified.
+               &Vbuffer_access_fontified_property,
+               doc: /* Property which (if non-nil) indicates text has been fontified.
 `buffer-substring' need not call the `buffer-access-fontify-functions'
 functions if all the text being accessed has this property.  */);
   Vbuffer_access_fontified_property = Qnil;
 
-  DEFVAR_LISP ("system-name", &Vsystem_name
-               /* The name of the machine Emacs is running on.  */);
+  DEFVAR_LISP ("system-name", &Vsystem_name,
+               doc: /* The name of the machine Emacs is running on.  */);
 
-  DEFVAR_LISP ("user-full-name", &Vuser_full_name
-               /* The full name of the user logged in.  */);
+  DEFVAR_LISP ("user-full-name", &Vuser_full_name,
+               doc: /* The full name of the user logged in.  */);
 
-  DEFVAR_LISP ("user-login-name", &Vuser_login_name
-               /* The user's name, taken from environment variables if possible.  */);
+  DEFVAR_LISP ("user-login-name", &Vuser_login_name,
+               doc: /* The user's name, taken from environment variables if possible.  */);
 
-  DEFVAR_LISP ("user-real-login-name", &Vuser_real_login_name
-               /* The user's name, based upon the real uid only.  */);
+  DEFVAR_LISP ("user-real-login-name", &Vuser_real_login_name,
+               doc: /* The user's name, based upon the real uid only.  */);
 
   defsubr (&Spropertize);
   defsubr (&Schar_equal);
diff --git a/src/term.c b/src/term.c
index 1ef1f2da929..65d0c8cedac 100644
--- a/src/term.c
+++ b/src/term.c
@@ -25,9 +25,9 @@ Boston, MA 02111-1307, USA.  */
 #include <stdio.h>
 #include <ctype.h>
 #include <string.h>
+
 #include "termchar.h"
 #include "termopts.h"
-#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "charset.h"
 #include "coding.h"
@@ -2176,8 +2176,8 @@ turn_off_face (f, face_id)
 
 DEFUN ("tty-display-color-p", Ftty_display_color_p, Stty_display_color_p,
        0, 1, 0,
-       /* Return non-nil if TTY can display colors on FRAME.  */
-       (frame))
+       doc: /* Return non-nil if TTY can display colors on FRAME.  */)
+     (frame)
      Lisp_Object frame;
 {
   return TN_max_colors > 0 ? Qt : Qnil;
@@ -2608,8 +2608,8 @@ fatal (str, arg1, arg2)
 void
 syms_of_term ()
 {
-  DEFVAR_BOOL ("system-uses-terminfo", &system_uses_terminfo
-    /* Non-nil means the system uses terminfo rather than termcap.
+  DEFVAR_BOOL ("system-uses-terminfo", &system_uses_terminfo,
+    doc: /* Non-nil means the system uses terminfo rather than termcap.
 This variable can be used by terminal emulator packages.  */);
 #ifdef TERMINFO
   system_uses_terminfo = 1;
@@ -2617,8 +2617,8 @@ This variable can be used by terminal emulator packages.  */);
   system_uses_terminfo = 0;
 #endif
 
-  DEFVAR_LISP ("ring-bell-function", &Vring_bell_function
-    /* Non-nil means call this function to ring the bell.
+  DEFVAR_LISP ("ring-bell-function", &Vring_bell_function,
+    doc: /* Non-nil means call this function to ring the bell.
 The function should accept no arguments.  */);
   Vring_bell_function = Qnil;
 
diff --git a/src/xdisp.c b/src/xdisp.c
index 08a378e689d..d967ac8d438 100644
--- a/src/xdisp.c
+++ b/src/xdisp.c
@@ -169,7 +169,7 @@ Boston, MA 02111-1307, USA.  */
 
 #include <config.h>
 #include <stdio.h>
-#define DOC_STRINGS_IN_COMMENTS
+
 #include "lisp.h"
 #include "keyboard.h"
 #include "frame.h"
@@ -7792,8 +7792,8 @@ tool_bar_lines_needed (f)
 
 DEFUN ("tool-bar-lines-needed", Ftool_bar_lines_needed, Stool_bar_lines_needed,
        0, 1, 0,
-       /* Return the number of lines occupied by the tool bar of FRAME.  */
-       (frame))
+       doc: /* Return the number of lines occupied by the tool bar of FRAME.  */)
+     (frame)
      Lisp_Object frame;
 {
   struct frame *f;
@@ -12161,11 +12161,11 @@ dump_glyph_row (row, vpos, glyphs)
 
 DEFUN ("dump-glyph-matrix", Fdump_glyph_matrix,
        Sdump_glyph_matrix, 0, 1, "p",
-       /* Dump the current matrix of the selected window to stderr.
+       doc: /* Dump the current matrix of the selected window to stderr.
 Shows contents of glyph row structures.  With non-nil
 parameter GLYPHS, dump glyphs as well.  If GLYPHS is 1 show
-glyphs in short form, otherwise show glyphs in long form.  */
-       (glyphs))
+glyphs in short form, otherwise show glyphs in long form.  */)
+     (glyphs)
      Lisp_Object glyphs;
 {
   struct window *w = XWINDOW (selected_window);
@@ -12183,11 +12183,11 @@ glyphs in short form, otherwise show glyphs in long form.  */
 
 
 DEFUN ("dump-glyph-row", Fdump_glyph_row, Sdump_glyph_row, 1, 2, "",
-       /* Dump glyph row ROW to stderr.
+       doc: /* Dump glyph row ROW to stderr.
 GLYPH 0 means don't dump glyphs.
 GLYPH 1 means dump glyphs in short form.
-GLYPH > 1 or omitted means dump glyphs in long form.  */
-       (row, glyphs))
+GLYPH > 1 or omitted means dump glyphs in long form.  */)
+     (row, glyphs)
      Lisp_Object row, glyphs;
 {
   struct glyph_matrix *matrix;
@@ -12205,11 +12205,11 @@ GLYPH > 1 or omitted means dump glyphs in long form.  */
 
 
 DEFUN ("dump-tool-bar-row", Fdump_tool_bar_row, Sdump_tool_bar_row, 1, 2, "",
-  /* Dump glyph row ROW of the tool-bar of the current frame to stderr.
+  doc: /* Dump glyph row ROW of the tool-bar of the current frame to stderr.
 GLYPH 0 means don't dump glyphs.
 GLYPH 1 means dump glyphs in short form.
-GLYPH > 1 or omitted means dump glyphs in long form.  */
-       (row, glyphs))
+GLYPH > 1 or omitted means dump glyphs in long form.  */)
+     (row, glyphs)
      Lisp_Object row, glyphs;
 {
   struct frame *sf = SELECTED_FRAME ();
@@ -12226,9 +12226,9 @@ GLYPH > 1 or omitted means dump glyphs in long form.  */
 
 
 DEFUN ("trace-redisplay", Ftrace_redisplay, Strace_redisplay, 0, 1, "P",
-       /* Toggle tracing of redisplay.
-With ARG, turn tracing on if and only if ARG is positive.  */
-       (arg))
+       doc: /* Toggle tracing of redisplay.
+With ARG, turn tracing on if and only if ARG is positive.  */)
+     (arg)
      Lisp_Object arg;
 {
   if (NILP (arg))
@@ -12244,8 +12244,8 @@ With ARG, turn tracing on if and only if ARG is positive.  */
 
 
 DEFUN ("trace-to-stderr", Ftrace_to_stderr, Strace_to_stderr, 1, MANY, "",
-       /* Like `format', but print result to stderr.  */
-       (nargs, args))
+       doc: /* Like `format', but print result to stderr.  */)
+     (nargs, args)
      int nargs;
      Lisp_Object *args;
 {
@@ -14662,97 +14662,97 @@ syms_of_xdisp ()
   Vmessages_buffer_name = build_string ("*Messages*");
   staticpro (&Vmessages_buffer_name);
   
-  DEFVAR_LISP ("show-trailing-whitespace", &Vshow_trailing_whitespace
-    /* Non-nil means highlight trailing whitespace.
+  DEFVAR_LISP ("show-trailing-whitespace", &Vshow_trailing_whitespace,
+    doc: /* Non-nil means highlight trailing whitespace.
 The face used for trailing whitespace is `trailing-whitespace'.  */);
   Vshow_trailing_whitespace = Qnil;
 
-  DEFVAR_LISP ("inhibit-redisplay", &Vinhibit_redisplay
-    /* Non-nil means don't actually do any redisplay.
+  DEFVAR_LISP ("inhibit-redisplay", &Vinhibit_redisplay,
+    doc: /* Non-nil means don't actually do any redisplay.
 This is used for internal purposes.  */);
   Vinhibit_redisplay = Qnil;
 
-  DEFVAR_LISP ("global-mode-string", &Vglobal_mode_string
-    /* String (or mode line construct) included (normally) in `mode-line-format'.  */);
+  DEFVAR_LISP ("global-mode-string", &Vglobal_mode_string,
+    doc: /* String (or mode line construct) included (normally) in `mode-line-format'.  */);
   Vglobal_mode_string = Qnil;
 
-  DEFVAR_LISP ("overlay-arrow-position", &Voverlay_arrow_position
-    /* Marker for where to display an arrow on top of the buffer text.
+  DEFVAR_LISP ("overlay-arrow-position", &Voverlay_arrow_position,
+    doc: /* Marker for where to display an arrow on top of the buffer text.
 This must be the beginning of a line in order to work.
 See also `overlay-arrow-string'.  */);
   Voverlay_arrow_position = Qnil;
 
-  DEFVAR_LISP ("overlay-arrow-string", &Voverlay_arrow_string
-    /* String to display as an arrow.  See also `overlay-arrow-position'.  */);
+  DEFVAR_LISP ("overlay-arrow-string", &Voverlay_arrow_string,
+    doc: /* String to display as an arrow.  See also `overlay-arrow-position'.  */);
   Voverlay_arrow_string = Qnil;
 
-  DEFVAR_INT ("scroll-step", &scroll_step
-    /* *The number of lines to try scrolling a window by when point moves out.
+  DEFVAR_INT ("scroll-step", &scroll_step,
+    doc: /* *The number of lines to try scrolling a window by when point moves out.
 If that fails to bring point back on frame, point is centered instead.
 If this is zero, point is always centered after it moves off frame.
 If you want scrolling to always be a line at a time, you should set
 `scroll-conservatively' to a large value rather than set this to 1.  */);
 
-  DEFVAR_INT ("scroll-conservatively", &scroll_conservatively
-    /* *Scroll up to this many lines, to bring point back on screen.
+  DEFVAR_INT ("scroll-conservatively", &scroll_conservatively,
+    doc: /* *Scroll up to this many lines, to bring point back on screen.
 A value of zero means to scroll the text to center point vertically
 in the window.  */);
   scroll_conservatively = 0;
 
-  DEFVAR_INT ("scroll-margin", &scroll_margin
-    /* *Number of lines of margin at the top and bottom of a window.
+  DEFVAR_INT ("scroll-margin", &scroll_margin,
+    doc: /* *Number of lines of margin at the top and bottom of a window.
 Recenter the window whenever point gets within this many lines
 of the top or bottom of the window.  */);
   scroll_margin = 0;
 
 #if GLYPH_DEBUG
-  DEFVAR_INT ("debug-end-pos", &debug_end_pos /* Don't ask.  */);
+  DEFVAR_INT ("debug-end-pos", &debug_end_pos, doc: /* Don't ask.  */);
 #endif
 
   DEFVAR_BOOL ("truncate-partial-width-windows",
-               &truncate_partial_width_windows
-    /* *Non-nil means truncate lines in all windows less than full frame wide.  */);
+               &truncate_partial_width_windows,
+    doc: /* *Non-nil means truncate lines in all windows less than full frame wide.  */);
   truncate_partial_width_windows = 1;
 
-  DEFVAR_BOOL ("mode-line-inverse-video", &mode_line_inverse_video
-    /* nil means display the mode-line/header-line/menu-bar in the default face.
+  DEFVAR_BOOL ("mode-line-inverse-video", &mode_line_inverse_video,
+    doc: /* nil means display the mode-line/header-line/menu-bar in the default face.
 Any other value means to use the appropriate face, `mode-line',
 `header-line', or `menu' respectively.
 
 This variable is deprecated; please change the above faces instead.  */);
   mode_line_inverse_video = 1;
 
-  DEFVAR_LISP ("line-number-display-limit", &Vline_number_display_limit
-    /* *Maximum buffer size for which line number should be displayed.
+  DEFVAR_LISP ("line-number-display-limit", &Vline_number_display_limit,
+    doc: /* *Maximum buffer size for which line number should be displayed.
 If the buffer is bigger than this, the line number does not appear
 in the mode line.  A value of nil means no limit.  */);
   Vline_number_display_limit = Qnil;
 
   DEFVAR_INT ("line-number-display-limit-width",
-              &line_number_display_limit_width
-    /* *Maximum line width (in characters) for line number display.
+              &line_number_display_limit_width,
+    doc: /* *Maximum line width (in characters) for line number display.
 If the average length of the lines near point is bigger than this, then the
 line number may be omitted from the mode line.  */);
   line_number_display_limit_width = 200;
 
-  DEFVAR_BOOL ("highlight-nonselected-windows", &highlight_nonselected_windows
-    /* *Non-nil means highlight region even in nonselected windows.  */);
+  DEFVAR_BOOL ("highlight-nonselected-windows", &highlight_nonselected_windows,
+    doc: /* *Non-nil means highlight region even in nonselected windows.  */);
   highlight_nonselected_windows = 0;
 
-  DEFVAR_BOOL ("multiple-frames", &multiple_frames
-    /* Non-nil if more than one frame is visible on this display.
+  DEFVAR_BOOL ("multiple-frames", &multiple_frames,
+    doc: /* Non-nil if more than one frame is visible on this display.
 Minibuffer-only frames don't count, but iconified frames do.
 This variable is not guaranteed to be accurate except while processing
 `frame-title-format' and `icon-title-format'.  */);
 
-  DEFVAR_LISP ("frame-title-format", &Vframe_title_format
-    /* Template for displaying the title bar of visible frames.
+  DEFVAR_LISP ("frame-title-format", &Vframe_title_format,
+    doc: /* Template for displaying the title bar of visible frames.
 \(Assuming the window manager supports this feature.)
 This variable has the same structure as `mode-line-format' (which see),
 and is used only on frames for which no explicit name has been set
 \(see `modify-frame-parameters').  */);
-  DEFVAR_LISP ("icon-title-format", &Vicon_title_format
-    /* Template for displaying the title bar of an iconified frame.
+  DEFVAR_LISP ("icon-title-format", &Vicon_title_format,
+    doc: /* Template for displaying the title bar of an iconified frame.
 \(Assuming the window manager supports this feature.)
 This variable has the same structure as `mode-line-format' (which see),
 and is used only on frames for which no explicit name has been set
@@ -14768,52 +14768,52 @@ and is used only on frames for which no explicit name has been set
                                                                Qnil)))),
                            Qnil)));
 
-  DEFVAR_LISP ("message-log-max", &Vmessage_log_max
-    /* Maximum number of lines to keep in the message log buffer.
+  DEFVAR_LISP ("message-log-max", &Vmessage_log_max,
+    doc: /* Maximum number of lines to keep in the message log buffer.
 If nil, disable message logging.  If t, log messages but don't truncate
 the buffer when it becomes large.  */);
   Vmessage_log_max = make_number (50);
 
-  DEFVAR_LISP ("window-size-change-functions", &Vwindow_size_change_functions
-    /* Functions called before redisplay, if window sizes have changed.
+  DEFVAR_LISP ("window-size-change-functions", &Vwindow_size_change_functions,
+    doc: /* Functions called before redisplay, if window sizes have changed.
 The value should be a list of functions that take one argument.
 Just before redisplay, for each frame, if any of its windows have changed
 size since the last redisplay, or have been split or deleted,
 all the functions in the list are called, with the frame as argument.  */);
   Vwindow_size_change_functions = Qnil;
 
-  DEFVAR_LISP ("window-scroll-functions", &Vwindow_scroll_functions
-    /* List of Functions to call before redisplaying a window with scrolling.
+  DEFVAR_LISP ("window-scroll-functions", &Vwindow_scroll_functions,
+    doc: /* List of Functions to call before redisplaying a window with scrolling.
 Each function is called with two arguments, the window
 and its new display-start position.  Note that the value of `window-end'
 is not valid when these functions are called.  */);
   Vwindow_scroll_functions = Qnil;
   
-  DEFVAR_BOOL ("auto-resize-tool-bars", &auto_resize_tool_bars_p
-    /* *Non-nil means automatically resize tool-bars.
+  DEFVAR_BOOL ("auto-resize-tool-bars", &auto_resize_tool_bars_p,
+    doc: /* *Non-nil means automatically resize tool-bars.
 This increases a tool-bar's height if not all tool-bar items are visible.
 It decreases a tool-bar's height when it would display blank lines
 otherwise.  */);
   auto_resize_tool_bars_p = 1;
   
-  DEFVAR_BOOL ("auto-raise-tool-bar-buttons", &auto_raise_tool_bar_buttons_p
-    /* *Non-nil means raise tool-bar buttons when the mouse moves over them.  */);
+  DEFVAR_BOOL ("auto-raise-tool-bar-buttons", &auto_raise_tool_bar_buttons_p,
+    doc: /* *Non-nil means raise tool-bar buttons when the mouse moves over them.  */);
   auto_raise_tool_bar_buttons_p = 1;
 
-  DEFVAR_LISP ("tool-bar-button-margin", &Vtool_bar_button_margin
-    /* *Margin around tool-bar buttons in pixels.
+  DEFVAR_LISP ("tool-bar-button-margin", &Vtool_bar_button_margin,
+    doc: /* *Margin around tool-bar buttons in pixels.
 If an integer, use that for both horizontal and vertical margins.
 Otherwise, value should be a pair of integers `(HORZ : VERT)' with
 HORZ specifying the horizontal margin, and VERT specifying the
 vertical margin.  */);
   Vtool_bar_button_margin = make_number (DEFAULT_TOOL_BAR_BUTTON_MARGIN);
 
-  DEFVAR_INT ("tool-bar-button-relief", &tool_bar_button_relief
-    /* Relief thickness of tool-bar buttons.  */);
+  DEFVAR_INT ("tool-bar-button-relief", &tool_bar_button_relief,
+    doc: /* Relief thickness of tool-bar buttons.  */);
   tool_bar_button_relief = DEFAULT_TOOL_BAR_BUTTON_RELIEF;
 
-  DEFVAR_LISP ("fontification-functions", &Vfontification_functions
-    /* List of functions to call to fontify regions of text.
+  DEFVAR_LISP ("fontification-functions", &Vfontification_functions,
+    doc: /* List of functions to call to fontify regions of text.
 Each function is called with one argument POS.  Functions must
 fontify a region starting at POS in the current buffer, and give
 fontified regions the property `fontified'.  */);
@@ -14821,22 +14821,22 @@ fontified regions the property `fontified'.  */);
   Fmake_variable_buffer_local (Qfontification_functions);
 
   DEFVAR_BOOL ("unibyte-display-via-language-environment",
-               &unibyte_display_via_language_environment
-    /* *Non-nil means display unibyte text according to language environment.
+               &unibyte_display_via_language_environment,
+    doc: /* *Non-nil means display unibyte text according to language environment.
 Specifically this means that unibyte non-ASCII characters
 are displayed by converting them to the equivalent multibyte characters
 according to the current language environment.  As a result, they are
 displayed according to the current fontset.  */);
   unibyte_display_via_language_environment = 0;
 
-  DEFVAR_LISP ("max-mini-window-height", &Vmax_mini_window_height
-    /* *Maximum height for resizing mini-windows.
+  DEFVAR_LISP ("max-mini-window-height", &Vmax_mini_window_height,
+    doc: /* *Maximum height for resizing mini-windows.
 If a float, it specifies a fraction of the mini-window frame's height.
 If an integer, it specifies a number of lines.  */);
   Vmax_mini_window_height = make_float (0.25);
 
-  DEFVAR_LISP ("resize-mini-windows", &Vresize_mini_windows
-    /* *How to resize mini-windows.
+  DEFVAR_LISP ("resize-mini-windows", &Vresize_mini_windows,
+    doc: /* *How to resize mini-windows.
 A value of nil means don't automatically resize mini-windows.
 A value of t means resize them to fit the text displayed in them.
 A value of `grow-only', the default, means let mini-windows grow
@@ -14845,36 +14845,36 @@ go back to their normal size.  */);
   Vresize_mini_windows = Qgrow_only;
 
   DEFVAR_BOOL ("cursor-in-non-selected-windows",
-               &cursor_in_non_selected_windows
-    /* *Non-nil means display a hollow cursor in non-selected windows.
+               &cursor_in_non_selected_windows,
+    doc: /* *Non-nil means display a hollow cursor in non-selected windows.
 Nil means don't display a cursor there.  */);
   cursor_in_non_selected_windows = 1;
   
-  DEFVAR_BOOL ("automatic-hscrolling", &automatic_hscrolling_p
-    /* *Non-nil means scroll the display automatically to make point visible.  */);
+  DEFVAR_BOOL ("automatic-hscrolling", &automatic_hscrolling_p,
+    doc: /* *Non-nil means scroll the display automatically to make point visible.  */);
   automatic_hscrolling_p = 1;
   
-  DEFVAR_LISP ("image-types", &Vimage_types
-    /* List of supported image types.
+  DEFVAR_LISP ("image-types", &Vimage_types,
+    doc: /* List of supported image types.
 Each element of the list is a symbol for a supported image type.  */);
   Vimage_types = Qnil;
   
-  DEFVAR_BOOL ("message-truncate-lines", &message_truncate_lines
-    /* If non-nil, messages are truncated instead of resizing the echo area.
+  DEFVAR_BOOL ("message-truncate-lines", &message_truncate_lines,
+    doc: /* If non-nil, messages are truncated instead of resizing the echo area.
 Bind this around calls to `message' to let it take effect.  */);
   message_truncate_lines = 0;
 
-  DEFVAR_LISP ("menu-bar-update-hook",  &Vmenu_bar_update_hook
-    /* Normal hook run for clicks on menu bar, before displaying a submenu.
+  DEFVAR_LISP ("menu-bar-update-hook",  &Vmenu_bar_update_hook,
+    doc: /* Normal hook run for clicks on menu bar, before displaying a submenu.
 Can be used to update submenus whose contents should vary.  */);
   Vmenu_bar_update_hook = Qnil;
   
-  DEFVAR_BOOL ("inhibit-menubar-update", &inhibit_menubar_update
-    /* Non-nil means don't update menu bars.  Internal use only.  */);
+  DEFVAR_BOOL ("inhibit-menubar-update", &inhibit_menubar_update,
+    doc: /* Non-nil means don't update menu bars.  Internal use only.  */);
   inhibit_menubar_update = 0;
 
-  DEFVAR_BOOL ("inhibit-eval-during-redisplay", &inhibit_eval_during_redisplay
-    /* Non-nil means don't eval Lisp during redisplay.  */);
+  DEFVAR_BOOL ("inhibit-eval-during-redisplay", &inhibit_eval_during_redisplay,
+    doc: /* Non-nil means don't eval Lisp during redisplay.  */);
   inhibit_eval_during_redisplay = 0;
 }
 
diff --git a/src/xfaces.c b/src/xfaces.c
index c9867c4ce1f..9971541cd31 100644
--- a/src/xfaces.c
+++ b/src/xfaces.c
@@ -194,7 +194,7 @@ Boston, MA 02111-1307, USA.  */
 #include <config.h>
 #include <sys/types.h>
 #include <sys/stat.h>
-#define DOC_STRINGS_IN_COMMENTS
+
 #include "lisp.h"
 #include "charset.h"
 #include "keyboard.h"
@@ -669,8 +669,8 @@ unregister_colors (pixels, n)
 
 
 DEFUN ("dump-colors", Fdump_colors, Sdump_colors, 0, 0, 0,
-       /* Dump currently allocated colors to stderr.  */
-       ())
+       doc: /* Dump currently allocated colors to stderr.  */)
+     ()
 {
   int i, n;
 
@@ -1017,9 +1017,9 @@ clear_face_cache (clear_fonts_p)
 
 
 DEFUN ("clear-face-cache", Fclear_face_cache, Sclear_face_cache, 0, 1, 0,
-       /* Clear face caches on all frames.
-Optional THOROUGHLY non-nil means try to free unused fonts, too.  */
-       (thoroughly))
+       doc: /* Clear face caches on all frames.
+Optional THOROUGHLY non-nil means try to free unused fonts, too.  */)
+     (thoroughly)
      Lisp_Object thoroughly;
 {
   clear_face_cache (!NILP (thoroughly));
@@ -1098,13 +1098,13 @@ clear_font_table (dpyinfo)
 #ifdef HAVE_WINDOW_SYSTEM
 
 DEFUN ("bitmap-spec-p", Fbitmap_spec_p, Sbitmap_spec_p, 1, 1, 0,
-       /* Value is non-nil if OBJECT is a valid bitmap specification.
+       doc: /* Value is non-nil if OBJECT is a valid bitmap specification.
 A bitmap specification is either a string, a file name, or a list
 \(WIDTH HEIGHT DATA) where WIDTH is the pixel width of the bitmap,
 HEIGHT is its height, and DATA is a string containing the bits of
 the pixmap.  Bits are stored row by row, each row occupies
-\(WIDTH + 7)/8 bytes.  */
-       (object))
+\(WIDTH + 7)/8 bytes.  */)
+     (object)
      Lisp_Object object;
 {
   int pixmap_p = 0;
@@ -1482,10 +1482,10 @@ face_color_supported_p (f, color_name, background_p)
 
 
 DEFUN ("color-gray-p", Fcolor_gray_p, Scolor_gray_p, 1, 2, 0,
-       /* Return non-nil if COLOR is a shade of gray (or white or black).
+       doc: /* Return non-nil if COLOR is a shade of gray (or white or black).
 FRAME specifies the frame and thus the display for interpreting COLOR.
-If FRAME is nil or omitted, use the selected frame.  */
-       (color, frame))
+If FRAME is nil or omitted, use the selected frame.  */)
+     (color, frame)
      Lisp_Object color, frame;
 {
   struct frame *f;
@@ -1499,11 +1499,11 @@ If FRAME is nil or omitted, use the selected frame.  */
 
 DEFUN ("color-supported-p", Fcolor_supported_p,
        Scolor_supported_p, 2, 3, 0,
-       /* Return non-nil if COLOR can be displayed on FRAME.
+       doc: /* Return non-nil if COLOR can be displayed on FRAME.
 BACKGROUND-P non-nil means COLOR is used as a background.
 If FRAME is nil or omitted, use the selected frame.
-COLOR must be a valid color name.  */
-       (color, frame, background_p))
+COLOR must be a valid color name.  */)
+     (color, frame, background_p)
      Lisp_Object frame, color, background_p;
 {
   struct frame *f;
@@ -2692,7 +2692,7 @@ remove_duplicates (list)
 
 
 DEFUN ("x-family-fonts", Fx_family_fonts, Sx_family_fonts, 0, 2, 0,
-       /* Return a list of available fonts of family FAMILY on FRAME.
+       doc: /* Return a list of available fonts of family FAMILY on FRAME.
 If FAMILY is omitted or nil, list all families.
 Otherwise, FAMILY must be a string, possibly containing wildcards
 `?' and `*'.
@@ -2706,8 +2706,8 @@ face attributes.  FIXED-P is non-nil if the font is fixed-pitch.
 FULL is the full name of the font, and REGISTRY-AND-ENCODING is a string
 giving the registry and encoding of the font.
 The result list is sorted according to the current setting of
-the face font sort order.  */
-       (family, frame))
+the face font sort order.  */)
+     (family, frame)
      Lisp_Object family, frame;
 {
   struct frame *f = check_x_frame (frame);
@@ -2752,12 +2752,12 @@ the face font sort order.  */
 
 DEFUN ("x-font-family-list", Fx_font_family_list, Sx_font_family_list,
        0, 1, 0,
-       /* Return a list of available font families on FRAME.
+       doc: /* Return a list of available font families on FRAME.
 If FRAME is omitted or nil, use the selected frame.
 Value is a list of conses (FAMILY . FIXED-P) where FAMILY
 is a font family, and FIXED-P is non-nil if fonts of that family
-are fixed-pitch.  */
-       (frame))
+are fixed-pitch.  */)
+     (frame)
      Lisp_Object frame;
 {
   struct frame *f = check_x_frame (frame);
@@ -2799,7 +2799,7 @@ are fixed-pitch.  */
 
 
 DEFUN ("x-list-fonts", Fx_list_fonts, Sx_list_fonts, 1, 5, 0,
-       /* Return a list of the names of available fonts matching PATTERN.
+       doc: /* Return a list of the names of available fonts matching PATTERN.
 If optional arguments FACE and FRAME are specified, return only fonts
 the same size as FACE on FRAME.
 PATTERN is a string, perhaps with wildcard characters;
@@ -2817,8 +2817,8 @@ The optional fourth argument MAXIMUM sets a limit on how many
 fonts to match.  The first MAXIMUM fonts are reported.
 The optional fifth argument WIDTH, if specified, is a number of columns
 occupied by a character of a font.  In that case, return only fonts
-the WIDTH times as wide as FACE on FRAME.  */
-       (pattern, face, frame, maximum, width))
+the WIDTH times as wide as FACE on FRAME.  */)
+     (pattern, face, frame, maximum, width)
     Lisp_Object pattern, face, frame, maximum, width;
 {
   struct frame *f;
@@ -3624,12 +3624,12 @@ merge_face_vector_with_property (f, to, prop)
 
 DEFUN ("internal-make-lisp-face", Finternal_make_lisp_face,
        Sinternal_make_lisp_face, 1, 2, 0,
-       /* Make FACE, a symbol, a Lisp face with all attributes nil.
+       doc: /* Make FACE, a symbol, a Lisp face with all attributes nil.
 If FACE was not known as a face before, create a new one.
 If optional argument FRAME is specified, make a frame-local face
 for that frame.  Otherwise operate on the global face definition.
-Value is a vector of face attributes.  */
-       (face, frame))
+Value is a vector of face attributes.  */)
+     (face, frame)
      Lisp_Object face, frame;
 {
   Lisp_Object global_lface, lface;
@@ -3702,11 +3702,11 @@ Value is a vector of face attributes.  */
 
 DEFUN ("internal-lisp-face-p", Finternal_lisp_face_p,
        Sinternal_lisp_face_p, 1, 2, 0,
-       /* Return non-nil if FACE names a face.
+       doc: /* Return non-nil if FACE names a face.
 If optional second parameter FRAME is non-nil, check for the
 existence of a frame-local face with name FACE on that frame.
-Otherwise check for the existence of a global face.  */
-       (face, frame))
+Otherwise check for the existence of a global face.  */)
+     (face, frame)
      Lisp_Object face, frame;
 {
   Lisp_Object lface;
@@ -3725,14 +3725,14 @@ Otherwise check for the existence of a global face.  */
 
 DEFUN ("internal-copy-lisp-face", Finternal_copy_lisp_face,
        Sinternal_copy_lisp_face, 4, 4, 0,
-       /* Copy face FROM to TO.
+       doc: /* Copy face FROM to TO.
 If FRAME it t, copy the global face definition of FROM to the
 global face definition of TO.  Otherwise, copy the frame-local
 definition of FROM on FRAME to the frame-local definition of TO
 on NEW-FRAME, or FRAME if NEW-FRAME is nil.
 
-Value is TO.  */
-       (from, to, frame, new_frame))
+Value is TO.  */)
+     (from, to, frame, new_frame)
      Lisp_Object from, to, frame, new_frame;
 {
   Lisp_Object lface, copy;
@@ -3767,13 +3767,13 @@ Value is TO.  */
 
 DEFUN ("internal-set-lisp-face-attribute", Finternal_set_lisp_face_attribute,
        Sinternal_set_lisp_face_attribute, 3, 4, 0,
-       /* Set attribute ATTR of FACE to VALUE.
+       doc: /* Set attribute ATTR of FACE to VALUE.
 FRAME being a frame means change the face on that frame.
 FRAME nil means change the face of the selected frame.
 FRAME t means change the default for new frames.
 FRAME 0 means change the face on all frames, and change the default
-  for new frames.  */
-       (face, attr, value, frame))
+  for new frames.  */)
+     (face, attr, value, frame)
      Lisp_Object face, attr, value, frame;
 {
   Lisp_Object lface;
@@ -4311,9 +4311,8 @@ update_face_from_frame_parameter (f, param, new_value)
    doesn't take a frame argument.  */
 
 DEFUN ("internal-face-x-get-resource", Finternal_face_x_get_resource,
-       Sinternal_face_x_get_resource, 3, 3, 0,
-       /* */
-       (resource, class, frame))
+       Sinternal_face_x_get_resource, 3, 3, 0, doc: /* */)
+     (resource, class, frame)
      Lisp_Object resource, class, frame;
 {
   Lisp_Object value = Qnil;
@@ -4364,9 +4363,8 @@ face_boolean_x_resource_value (value, signal_p)
 DEFUN ("internal-set-lisp-face-attribute-from-resource",
        Finternal_set_lisp_face_attribute_from_resource,
        Sinternal_set_lisp_face_attribute_from_resource,
-       3, 4, 0,
-       /* */
-       (face, attr, value, frame))
+       3, 4, 0, doc: /* */)
+     (face, attr, value, frame)
      Lisp_Object face, attr, value, frame;
 {
   CHECK_SYMBOL (face, 0);
@@ -4495,13 +4493,13 @@ x_update_menu_appearance (f)
 DEFUN ("internal-get-lisp-face-attribute", Finternal_get_lisp_face_attribute,
        Sinternal_get_lisp_face_attribute,
        2, 3, 0,
-       /* Return face attribute KEYWORD of face SYMBOL.
+       doc: /* Return face attribute KEYWORD of face SYMBOL.
 If SYMBOL does not name a valid Lisp face or KEYWORD isn't a valid
 face attribute name, signal an error.
 If the optional argument FRAME is given, report on face FACE in that
 frame.  If FRAME is t, report on the defaults for face FACE (for new
-frames).  If FRAME is omitted or nil, use the selected frame.  */
-       (symbol, keyword, frame))
+frames).  If FRAME is omitted or nil, use the selected frame.  */)
+     (symbol, keyword, frame)
      Lisp_Object symbol, keyword, frame;
 {
   Lisp_Object lface, value = Qnil;
@@ -4560,9 +4558,9 @@ frames).  If FRAME is omitted or nil, use the selected frame.  */
 DEFUN ("internal-lisp-face-attribute-values",
        Finternal_lisp_face_attribute_values,
        Sinternal_lisp_face_attribute_values, 1, 1, 0,
-       /* Return a list of valid discrete values for face attribute ATTR.
-Value is nil if ATTR doesn't have a discrete set of valid values.  */
-       (attr))
+       doc: /* Return a list of valid discrete values for face attribute ATTR.
+Value is nil if ATTR doesn't have a discrete set of valid values.  */)
+     (attr)
      Lisp_Object attr;
 {
   Lisp_Object result = Qnil;
@@ -4612,9 +4610,9 @@ Value is nil if ATTR doesn't have a discrete set of valid values.  */
 
 DEFUN ("internal-merge-in-global-face", Finternal_merge_in_global_face,
        Sinternal_merge_in_global_face, 2, 2, 0,
-  /* Add attributes from frame-default definition of FACE to FACE on FRAME.
-Default face attributes override any local face attributes.  */
-       (face, frame))
+  doc: /* Add attributes from frame-default definition of FACE to FACE on FRAME.
+Default face attributes override any local face attributes.  */)
+     (face, frame)
      Lisp_Object face, frame;
 {
   int i;
@@ -4647,13 +4645,13 @@ Default face attributes override any local face attributes.  */
    done in fontset.el.  */
 
 DEFUN ("face-font", Fface_font, Sface_font, 1, 2, 0,
-  /* Return the font name of face FACE, or nil if it is unspecified.
+  doc: /* Return the font name of face FACE, or nil if it is unspecified.
 If the optional argument FRAME is given, report on face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE (for new frames).
   The font default for a face is either nil, or a list
   of the form (bold), (italic) or (bold italic).
-If FRAME is omitted or nil, use the selected frame.  */
-       (face, frame))
+If FRAME is omitted or nil, use the selected frame.  */)
+     (face, frame)
      Lisp_Object face, frame;
 {
   if (EQ (frame, Qt))
@@ -4731,11 +4729,11 @@ lface_equal_p (v1, v2)
 
 DEFUN ("internal-lisp-face-equal-p", Finternal_lisp_face_equal_p,
        Sinternal_lisp_face_equal_p, 2, 3, 0,
-       /* True if FACE1 and FACE2 are equal.
+       doc: /* True if FACE1 and FACE2 are equal.
 If the optional argument FRAME is given, report on face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE (for new frames).
-If FRAME is omitted or nil, use the selected frame.  */
-       (face1, face2, frame))
+If FRAME is omitted or nil, use the selected frame.  */)
+     (face1, face2, frame)
      Lisp_Object face1, face2, frame;
 {
   int equal_p;
@@ -4761,11 +4759,11 @@ If FRAME is omitted or nil, use the selected frame.  */
 
 DEFUN ("internal-lisp-face-empty-p", Finternal_lisp_face_empty_p,
        Sinternal_lisp_face_empty_p, 1, 2, 0,
-       /* True if FACE has no attribute specified.
+       doc: /* True if FACE has no attribute specified.
 If the optional argument FRAME is given, report on face FACE in that frame.
 If FRAME is t, report on the defaults for face FACE (for new frames).
-If FRAME is omitted or nil, use the selected frame.  */
-       (face, frame))
+If FRAME is omitted or nil, use the selected frame.  */)
+     (face, frame)
      Lisp_Object face, frame;
 {
   struct frame *f;
@@ -4792,9 +4790,9 @@ If FRAME is omitted or nil, use the selected frame.  */
 
 DEFUN ("frame-face-alist", Fframe_face_alist, Sframe_face_alist,
        0, 1, 0,
-       /* Return an alist of frame-local faces defined on FRAME.
-For internal use only.  */
-       (frame))
+       doc: /* Return an alist of frame-local faces defined on FRAME.
+For internal use only.  */)
+     (frame)
      Lisp_Object frame;
 {
   struct frame *f = frame_or_selected_frame (frame, 0);
@@ -5471,14 +5469,14 @@ lookup_derived_face (f, symbol, c, face_id)
 DEFUN ("internal-set-font-selection-order",
        Finternal_set_font_selection_order,
        Sinternal_set_font_selection_order, 1, 1, 0,
-       /* Set font selection order for face font selection to ORDER.
+       doc: /* Set font selection order for face font selection to ORDER.
 ORDER must be a list of length 4 containing the symbols `:width',
 `:height', `:weight', and `:slant'.  Face attributes appearing
 first in ORDER are matched first, e.g. if `:height' appears before
 `:weight' in ORDER, font selection first tries to find a font with
 a suitable height, and then tries to match the font weight.
-Value is ORDER.  */
-       (order))
+Value is ORDER.  */)
+     (order)
      Lisp_Object order;
 {
   Lisp_Object list;
@@ -5531,11 +5529,11 @@ Value is ORDER.  */
 DEFUN ("internal-set-alternative-font-family-alist",
        Finternal_set_alternative_font_family_alist,
        Sinternal_set_alternative_font_family_alist, 1, 1, 0,
-  /* Define alternative font families to try in face font selection.
+  doc: /* Define alternative font families to try in face font selection.
 ALIST is an alist of (FAMILY ALTERNATIVE1 ALTERNATIVE2 ...) entries.
 Each ALTERNATIVE is tried in order if no fonts of font family FAMILY can
-be found.  Value is ALIST.  */
-       (alist))
+be found.  Value is ALIST.  */)
+     (alist)
      Lisp_Object alist;
 {
   CHECK_LIST (alist, 0);
@@ -5548,11 +5546,11 @@ be found.  Value is ALIST.  */
 DEFUN ("internal-set-alternative-font-registry-alist",
        Finternal_set_alternative_font_registry_alist,
        Sinternal_set_alternative_font_registry_alist, 1, 1, 0,
-  /* Define alternative font registries to try in face font selection.
+  doc: /* Define alternative font registries to try in face font selection.
 ALIST is an alist of (REGISTRY ALTERNATIVE1 ALTERNATIVE2 ...) entries.
 Each ALTERNATIVE is tried in order if no fonts of font registry REGISTRY can
-be found.  Value is ALIST.  */
-       (alist))
+be found.  Value is ALIST.  */)
+     (alist)
      Lisp_Object alist;
 {
   CHECK_LIST (alist, 0);
@@ -6659,13 +6657,13 @@ realize_tty_face (cache, attrs, c)
 DEFUN ("tty-suppress-bold-inverse-default-colors",
        Ftty_suppress_bold_inverse_default_colors,
        Stty_suppress_bold_inverse_default_colors, 1, 1, 0,
-  /* Suppress/allow boldness of faces with inverse default colors.
+  doc: /* Suppress/allow boldness of faces with inverse default colors.
 SUPPRESS non-nil means suppress it.
 This affects bold faces on TTYs whose foreground is the default background
 color of the display and whose background is the default foreground color.
 For such faces, the bold face attribute is ignored if this variable
-is non-nil.  */
-       (suppress))
+is non-nil.  */)
+     (suppress)
      Lisp_Object suppress;
 {
   tty_suppress_bold_inverse_default_colors_p = !NILP (suppress);
@@ -6981,8 +6979,8 @@ dump_realized_face (face)
 }
 
 
-DEFUN ("dump-face", Fdump_face, Sdump_face, 0, 1, 0, /* */
-       (n))
+DEFUN ("dump-face", Fdump_face, Sdump_face, 0, 1, 0, doc: /* */)
+     (n)
      Lisp_Object n;
 {
   if (NILP (n))
@@ -7016,8 +7014,8 @@ DEFUN ("dump-face", Fdump_face, Sdump_face, 0, 1, 0, /* */
 
 
 DEFUN ("show-face-resources", Fshow_face_resources, Sshow_face_resources,
-       0, 0, 0, /* */
-       ())
+       0, 0, 0, doc: /* */)
+     ()
 {
   fprintf (stderr, "number of colors = %d\n", ncolors_allocated);
   fprintf (stderr, "number of pixmaps = %d\n", npixmaps_allocated);
@@ -7209,29 +7207,29 @@ syms_of_xfaces ()
   defsubr (&Sdump_colors);
 #endif
 
-  DEFVAR_LISP ("font-list-limit", &Vfont_list_limit
-               /* *Limit for font matching.
+  DEFVAR_LISP ("font-list-limit", &Vfont_list_limit,
+               doc: /* *Limit for font matching.
 If an integer > 0, font matching functions won't load more than
 that number of fonts when searching for a matching font.  */);
   Vfont_list_limit = make_number (DEFAULT_FONT_LIST_LIMIT);
 
-  DEFVAR_LISP ("face-new-frame-defaults", &Vface_new_frame_defaults
-    /* List of global face definitions (for internal use only.)  */);
+  DEFVAR_LISP ("face-new-frame-defaults", &Vface_new_frame_defaults,
+    doc: /* List of global face definitions (for internal use only.)  */);
   Vface_new_frame_defaults = Qnil;
 
-  DEFVAR_LISP ("face-default-stipple", &Vface_default_stipple
-    /* *Default stipple pattern used on monochrome displays.
+  DEFVAR_LISP ("face-default-stipple", &Vface_default_stipple,
+    doc: /* *Default stipple pattern used on monochrome displays.
 This stipple pattern is used on monochrome displays
 instead of shades of gray for a face background color.
 See `set-face-stipple' for possible values for this variable.  */);
   Vface_default_stipple = build_string ("gray3");
 
-  DEFVAR_LISP ("tty-defined-color-alist", &Vtty_defined_color_alist
-   /* An alist of defined terminal colors and their RGB values.  */);
+  DEFVAR_LISP ("tty-defined-color-alist", &Vtty_defined_color_alist,
+   doc: /* An alist of defined terminal colors and their RGB values.  */);
   Vtty_defined_color_alist = Qnil;
 
-  DEFVAR_LISP ("scalable-fonts-allowed", &Vscalable_fonts_allowed
-               /* Allowed scalable fonts.
+  DEFVAR_LISP ("scalable-fonts-allowed", &Vscalable_fonts_allowed,
+               doc: /* Allowed scalable fonts.
 A value of nil means don't allow any scalable fonts.
 A value of t means allow any scalable font.
 Otherwise, value must be a list of regular expressions.  A font may be
@@ -7240,8 +7238,8 @@ Note that if value is nil, a scalable font might still be used, if no
 other font of the appropriate family and registry is available.  */);
   Vscalable_fonts_allowed = Qnil;
 
-  DEFVAR_LISP ("face-ignored-fonts", &Vface_ignored_fonts
-               /* List of ignored fonts.
+  DEFVAR_LISP ("face-ignored-fonts", &Vface_ignored_fonts,
+               doc: /* List of ignored fonts.
 Each element is a regular expression that matches names of fonts to
 ignore.  */);
   Vface_ignored_fonts = Qnil;
diff --git a/src/xfns.c b/src/xfns.c
index c43dd482271..22c5bd91254 100644
--- a/src/xfns.c
+++ b/src/xfns.c
@@ -19,8 +19,6 @@ along with GNU Emacs; see the file COPYING.  If not, write to
 the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA 02111-1307, USA.  */
 
-#define DOC_STRINGS_IN_COMMENTS
-
 #include <config.h>
 #include <signal.h>
 #include <stdio.h>
@@ -2641,7 +2639,7 @@ validate_x_resource_name ()
 extern char *x_get_string_resource ();
 
 DEFUN ("x-get-resource", Fx_get_resource, Sx_get_resource, 2, 4, 0,
-  /* Return the value of ATTRIBUTE, of class CLASS, from the X defaults database.
+  doc: /* Return the value of ATTRIBUTE, of class CLASS, from the X defaults database.
 This uses `INSTANCE.ATTRIBUTE' as the key and `Emacs.CLASS' as the
 class, where INSTANCE is the name under which Emacs was invoked, or
 the name specified by the `-name' or `-rn' command-line arguments.
@@ -2649,8 +2647,8 @@ the name specified by the `-name' or `-rn' command-line arguments.
 The optional arguments COMPONENT and SUBCLASS add to the key and the
 class, respectively.  You must specify both of them or neither.
 If you specify them, the key is `INSTANCE.COMPONENT.ATTRIBUTE'
-and the class is `Emacs.CLASS.SUBCLASS'.  */
-       (attribute, class, component, subclass))
+and the class is `Emacs.CLASS.SUBCLASS'.  */)
+     (attribute, class, component, subclass)
      Lisp_Object attribute, class, component, subclass;
 {
   register char *value;
@@ -2999,13 +2997,13 @@ x_default_scroll_bar_color_parameter (f, alist, prop, xprop, xclass,
 
 
 DEFUN ("x-parse-geometry", Fx_parse_geometry, Sx_parse_geometry, 1, 1, 0,
-       /* Parse an X-style geometry string STRING.
+       doc: /* Parse an X-style geometry string STRING.
 Returns an alist of the form ((top . TOP), (left . LEFT) ... ).
 The properties returned may include `top', `left', `height', and `width'.
 The value of `left' or `top' may be an integer,
 or a list (+ N) meaning N pixels relative to top/left corner,
-or a list (- N) meaning -N pixels relative to bottom/right corner.  */
-       (string))
+or a list (- N) meaning -N pixels relative to bottom/right corner.  */)
+     (string)
      Lisp_Object string;
 {
   int geometry, x, y;
@@ -4092,7 +4090,7 @@ unwind_create_frame (frame)
 
 DEFUN ("x-create-frame", Fx_create_frame, Sx_create_frame,
        1, 1, 0,
-       /* Make a new X window, which is called a "frame" in Emacs terms.
+       doc: /* Make a new X window, which is called a "frame" in Emacs terms.
 Returns an Emacs frame object.
 ALIST is an alist of frame parameters.
 If the parameters specify that the frame should not have a minibuffer,
@@ -4100,8 +4098,8 @@ and do not specify a specific minibuffer window to use,
 then `default-minibuffer-frame' must be a frame whose minibuffer can
 be shared by the new frame.
 
-This function is an internal primitive--use `make-frame' instead.  */
-       (parms))
+This function is an internal primitive--use `make-frame' instead.  */)
+     (parms)
      Lisp_Object parms;
 {
   struct frame *f;
@@ -4555,9 +4553,9 @@ x_get_focus_frame (frame)
    following a user-command.  */
 
 DEFUN ("x-focus-frame", Fx_focus_frame, Sx_focus_frame, 1, 1, 0,
-       /* Set the input focus to FRAME.
-FRAME nil means use the selected frame.  */
-       (frame))
+       doc: /* Set the input focus to FRAME.
+FRAME nil means use the selected frame.  */)
+     (frame)
      Lisp_Object frame;
 {
   struct frame *f = check_x_frame (frame);
@@ -4576,8 +4574,8 @@ FRAME nil means use the selected frame.  */
 
 
 DEFUN ("xw-color-defined-p", Fxw_color_defined_p, Sxw_color_defined_p, 1, 2, 0,
-       /* Internal function called by `color-defined-p', which see.  */
-       (color, frame))
+       doc: /* Internal function called by `color-defined-p', which see.  */)
+     (color, frame)
      Lisp_Object color, frame;
 {
   XColor foo;
@@ -4592,8 +4590,8 @@ DEFUN ("xw-color-defined-p", Fxw_color_defined_p, Sxw_color_defined_p, 1, 2, 0,
 }
 
 DEFUN ("xw-color-values", Fxw_color_values, Sxw_color_values, 1, 2, 0,
-       /* Internal function called by `color-values', which see.  */
-       (color, frame))
+       doc: /* Internal function called by `color-values', which see.  */)
+     (color, frame)
      Lisp_Object color, frame;
 {
   XColor foo;
@@ -4615,8 +4613,8 @@ DEFUN ("xw-color-values", Fxw_color_values, Sxw_color_values, 1, 2, 0,
 }
 
 DEFUN ("xw-display-color-p", Fxw_display_color_p, Sxw_display_color_p, 0, 1, 0,
-       /* Internal function called by `display-color-p', which see.  */
-       (display))
+       doc: /* Internal function called by `display-color-p', which see.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4639,12 +4637,12 @@ DEFUN ("xw-display-color-p", Fxw_display_color_p, Sxw_display_color_p, 0, 1, 0,
 
 DEFUN ("x-display-grayscale-p", Fx_display_grayscale_p, Sx_display_grayscale_p,
        0, 1, 0,
-       /* Return t if the X display supports shades of gray.
+       doc: /* Return t if the X display supports shades of gray.
 Note that color displays do support shades of gray.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4669,11 +4667,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 
 DEFUN ("x-display-pixel-width", Fx_display_pixel_width, Sx_display_pixel_width,
        0, 1, 0,
-       /* Returns the width in pixels of the X display DISPLAY.
+       doc: /* Returns the width in pixels of the X display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4683,11 +4681,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 
 DEFUN ("x-display-pixel-height", Fx_display_pixel_height,
        Sx_display_pixel_height, 0, 1, 0,
-       /* Returns the height in pixels of the X display DISPLAY.
+       doc: /* Returns the height in pixels of the X display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4697,11 +4695,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 
 DEFUN ("x-display-planes", Fx_display_planes, Sx_display_planes,
        0, 1, 0,
-       /* Returns the number of bitplanes of the X display DISPLAY.
+       doc: /* Returns the number of bitplanes of the X display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4711,11 +4709,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 
 DEFUN ("x-display-color-cells", Fx_display_color_cells, Sx_display_color_cells,
        0, 1, 0,
-       /* Returns the number of color cells of the X display DISPLAY.
+       doc: /* Returns the number of color cells of the X display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4727,11 +4725,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 DEFUN ("x-server-max-request-size", Fx_server_max_request_size,
        Sx_server_max_request_size,
        0, 1, 0,
-       /* Returns the maximum request size of the X server of display DISPLAY.
+       doc: /* Returns the maximum request size of the X server of display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4740,11 +4738,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 }
 
 DEFUN ("x-server-vendor", Fx_server_vendor, Sx_server_vendor, 0, 1, 0,
-       /* Returns the vendor ID string of the X server of display DISPLAY.
+       doc: /* Returns the vendor ID string of the X server of display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4755,15 +4753,15 @@ If omitted or nil, that stands for the selected frame's display.  */
 }
 
 DEFUN ("x-server-version", Fx_server_version, Sx_server_version, 0, 1, 0,
-       /* Returns the version numbers of the X server of display DISPLAY.
+       doc: /* Returns the version numbers of the X server of display DISPLAY.
 The value is a list of three integers: the major and minor
 version numbers of the X Protocol in use, and the vendor-specific release
 number.  See also the function `x-server-vendor'.
 
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4775,11 +4773,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 }
 
 DEFUN ("x-display-screens", Fx_display_screens, Sx_display_screens, 0, 1, 0,
-       /* Return the number of screens on the X server of display DISPLAY.
+       doc: /* Return the number of screens on the X server of display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4788,11 +4786,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 }
 
 DEFUN ("x-display-mm-height", Fx_display_mm_height, Sx_display_mm_height, 0, 1, 0,
-       /* Return the height in millimeters of the X display DISPLAY.
+       doc: /* Return the height in millimeters of the X display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4801,11 +4799,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 }
 
 DEFUN ("x-display-mm-width", Fx_display_mm_width, Sx_display_mm_width, 0, 1, 0,
-       /* Return the width in millimeters of the X display DISPLAY.
+       doc: /* Return the width in millimeters of the X display DISPLAY.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4815,12 +4813,12 @@ If omitted or nil, that stands for the selected frame's display.  */
 
 DEFUN ("x-display-backing-store", Fx_display_backing_store,
        Sx_display_backing_store, 0, 1, 0,
-       /* Returns an indication of whether X display DISPLAY does backing store.
+       doc: /* Returns an indication of whether X display DISPLAY does backing store.
 The value may be `always', `when-mapped', or `not-useful'.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4850,14 +4848,14 @@ If omitted or nil, that stands for the selected frame's display.  */
 
 DEFUN ("x-display-visual-class", Fx_display_visual_class,
        Sx_display_visual_class, 0, 1, 0,
-       /* Return the visual class of the X display DISPLAY.
+       doc: /* Return the visual class of the X display DISPLAY.
 The value is one of the symbols `static-gray', `gray-scale',
 `static-color', `pseudo-color', `true-color', or `direct-color'.
 
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -4893,11 +4891,11 @@ If omitted or nil, that stands for the selected frame's display.  */
 
 DEFUN ("x-display-save-under", Fx_display_save_under,
        Sx_display_save_under, 0, 1, 0,
-       /* Returns t if the X display DISPLAY supports the save-under feature.
+       doc: /* Returns t if the X display DISPLAY supports the save-under feature.
 The optional argument DISPLAY specifies which display to ask about.
 DISPLAY should be either a frame or a display name (a string).
-If omitted or nil, that stands for the selected frame's display.  */
-       (display))
+If omitted or nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -5114,12 +5112,12 @@ x_display_info_for_name (name)
 
 DEFUN ("x-open-connection", Fx_open_connection, Sx_open_connection,
        1, 3, 0,
-       /* Open a connection to an X server.
+       doc: /* Open a connection to an X server.
 DISPLAY is the name of the display to connect to.
 Optional second arg XRM-STRING is a string of resources in xrdb format.
 If the optional third arg MUST-SUCCEED is non-nil,
-terminate Emacs if we can't open the connection.  */
-       (display, xrm_string, must_succeed))
+terminate Emacs if we can't open the connection.  */)
+     (display, xrm_string, must_succeed)
      Lisp_Object display, xrm_string, must_succeed;
 {
   unsigned char *xrm_option;
@@ -5164,10 +5162,10 @@ connections from your machine.\n",
 
 DEFUN ("x-close-connection", Fx_close_connection,
        Sx_close_connection, 1, 1, 0,
-       /* Close the connection to DISPLAY's X server.
+       doc: /* Close the connection to DISPLAY's X server.
 For DISPLAY, specify either a frame or a display name (a string).
-If DISPLAY is nil, that stands for the selected frame's display.  */
-       (display))
+If DISPLAY is nil, that stands for the selected frame's display.  */)
+     (display)
      Lisp_Object display;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -5203,8 +5201,8 @@ If DISPLAY is nil, that stands for the selected frame's display.  */
 }
 
 DEFUN ("x-display-list", Fx_display_list, Sx_display_list, 0, 0, 0,
-       /* Return the list of display names that Emacs has connections to.  */
-       ())
+       doc: /* Return the list of display names that Emacs has connections to.  */)
+     ()
 {
   Lisp_Object tail, result;
 
@@ -5216,15 +5214,15 @@ DEFUN ("x-display-list", Fx_display_list, Sx_display_list, 0, 0, 0,
 }
 
 DEFUN ("x-synchronize", Fx_synchronize, Sx_synchronize, 1, 2, 0,
-       /* If ON is non-nil, report X errors as soon as the erring request is made.
+       doc: /* If ON is non-nil, report X errors as soon as the erring request is made.
 If ON is nil, allow buffering of requests.
 Turning on synchronization prohibits the Xlib routines from buffering
 requests and seriously degrades performance, but makes debugging much
 easier.
 The optional second argument DISPLAY specifies which display to act on.
 DISPLAY should be either a frame or a display name (a string).
-If DISPLAY is omitted or nil, that stands for the selected frame's display.  */
-       (on, display))
+If DISPLAY is omitted or nil, that stands for the selected frame's display.  */)
+     (on, display)
     Lisp_Object display, on;
 {
   struct x_display_info *dpyinfo = check_x_display_info (display);
@@ -5603,12 +5601,12 @@ image_spec_value (spec, key, found)
      
 
 DEFUN ("image-size", Fimage_size, Simage_size, 1, 3, 0,
-       /* Return the size of image SPEC as pair (WIDTH . HEIGHT).
+       doc: /* Return the size of image SPEC as pair (WIDTH . HEIGHT).
 PIXELS non-nil means return the size in pixels, otherwise return the
 size in canonical character units.
 FRAME is the frame on which the image will be displayed.  FRAME nil
-or omitted means use the selected frame.  */
-       (spec, pixels, frame))
+or omitted means use the selected frame.  */)
+     (spec, pixels, frame)
      Lisp_Object spec, pixels, frame;
 {
   Lisp_Object size;
@@ -5636,10 +5634,10 @@ or omitted means use the selected frame.  */
 
 
 DEFUN ("image-mask-p", Fimage_mask_p, Simage_mask_p, 1, 2, 0,
-       /* Return t if image SPEC has a mask bitmap.
+       doc: /* Return t if image SPEC has a mask bitmap.
 FRAME is the frame on which the image will be displayed.  FRAME nil
-or omitted means use the selected frame.  */
-       (spec, frame))
+or omitted means use the selected frame.  */)
+     (spec, frame)
      Lisp_Object spec, frame;
 {
   Lisp_Object mask;
@@ -5982,10 +5980,10 @@ clear_image_cache (f, force_p)
 
 DEFUN ("clear-image-cache", Fclear_image_cache, Sclear_image_cache,
        0, 1, 0,
-       /* Clear the image cache of FRAME.
+       doc: /* Clear the image cache of FRAME.
 FRAME nil or omitted means use the selected frame.
-FRAME t means clear the image caches of all frames.  */
-       (frame))
+FRAME t means clear the image caches of all frames.  */)
+     (frame)
      Lisp_Object frame;
 {
   if (EQ (frame, Qt))
@@ -10247,10 +10245,10 @@ x_kill_gs_process (pixmap, f)
 
 DEFUN ("x-change-window-property", Fx_change_window_property,
        Sx_change_window_property, 2, 3, 0,
-       /* Change window property PROP to VALUE on the X window of FRAME.
+       doc: /* Change window property PROP to VALUE on the X window of FRAME.
 PROP and VALUE must be strings.  FRAME nil or omitted means use the
-selected frame.  Value is VALUE.  */
-       (prop, value, frame))
+selected frame.  Value is VALUE.  */)
+     (prop, value, frame)
      Lisp_Object frame, prop, value;
 {
   struct frame *f = check_x_frame (frame);
@@ -10275,9 +10273,9 @@ selected frame.  Value is VALUE.  */
 
 DEFUN ("x-delete-window-property", Fx_delete_window_property,
        Sx_delete_window_property, 1, 2, 0,
-       /* Remove window property PROP from X window of FRAME.
-FRAME nil or omitted means use the selected frame.  Value is PROP.  */
-       (prop, frame))
+       doc: /* Remove window property PROP from X window of FRAME.
+FRAME nil or omitted means use the selected frame.  Value is PROP.  */)
+     (prop, frame)
      Lisp_Object prop, frame;
 {
   struct frame *f = check_x_frame (frame);
@@ -10298,11 +10296,11 @@ FRAME nil or omitted means use the selected frame.  Value is PROP.  */
 
 DEFUN ("x-window-property", Fx_window_property, Sx_window_property,
        1, 2, 0,
-       /* Value is the value of window property PROP on FRAME.
+       doc: /* Value is the value of window property PROP on FRAME.
 If FRAME is nil or omitted, use the selected frame.  Value is nil
 if FRAME hasn't a property with name PROP or if PROP has no string
-value.  */
-       (prop, frame))
+value.  */)
+     (prop, frame)
      Lisp_Object prop, frame;
 {
   struct frame *f = check_x_frame (frame);
@@ -10941,7 +10939,7 @@ compute_tip_xy (f, parms, dx, dy, width, height, root_x, root_y)
 
 
 DEFUN ("x-show-tip", Fx_show_tip, Sx_show_tip, 1, 6, 0,
-       /* Show STRING in a "tooltip" window on frame FRAME.
+       doc: /* Show STRING in a "tooltip" window on frame FRAME.
 A tooltip window is a small X window displaying a string.
 
 FRAME nil or omitted means use the selected frame.
@@ -10961,8 +10959,8 @@ window, otherwise it is displayed at the mouse position, with offset
 DY added (default is -10).
 
 A tooltip's maximum size is specified by `x-max-tooltip-size'.
-Text larger than the specified size is clipped.  */
-       (string, frame, parms, timeout, dx, dy))
+Text larger than the specified size is clipped.  */)
+     (string, frame, parms, timeout, dx, dy)
      Lisp_Object string, frame, parms, timeout, dx, dy;
 {
   struct frame *f;
@@ -11150,9 +11148,9 @@ Text larger than the specified size is clipped.  */
 
 
 DEFUN ("x-hide-tip", Fx_hide_tip, Sx_hide_tip, 0, 0, 0,
-       /* Hide the current tooltip window, if there is any.
-Value is t if tooltip was open, nil otherwise.  */
-       ())
+       doc: /* Hide the current tooltip window, if there is any.
+Value is t if tooltip was open, nil otherwise.  */)
+     ()
 {
   int count;
   Lisp_Object deleted, frame, timer;
@@ -11240,12 +11238,12 @@ file_dialog_unmap_cb (widget, client_data, call_data)
 
 
 DEFUN ("x-file-dialog", Fx_file_dialog, Sx_file_dialog, 2, 4, 0,
-       /* Read file name, prompting with PROMPT in directory DIR.
+       doc: /* Read file name, prompting with PROMPT in directory DIR.
 Use a file selection dialog.
 Select DEFAULT-FILENAME in the dialog's file selection box, if
 specified.  Don't let the user enter a file name in the file
-selection dialog's entry field, if MUSTMATCH is non-nil.  */
-       (prompt, dir, default_filename, mustmatch))
+selection dialog's entry field, if MUSTMATCH is non-nil.  */)
+     (prompt, dir, default_filename, mustmatch)
      Lisp_Object prompt, dir, default_filename, mustmatch;
 {
   int result;
@@ -11398,11 +11396,11 @@ selection dialog's entry field, if MUSTMATCH is non-nil.  */
 
 DEFUN ("x-backspace-delete-keys-p", Fx_backspace_delete_keys_p,
        Sx_backspace_delete_keys_p, 0, 1, 0,
-       /* Check if both Backspace and Delete keys are on the keyboard of FRAME.
+       doc: /* Check if both Backspace and Delete keys are on the keyboard of FRAME.
 FRAME nil means use the selected frame.
 Value is t if we know that both keys are present, and are mapped to the
-usual X keysyms.  */
-       (frame))
+usual X keysyms.  */)
+     (frame)
      Lisp_Object frame;
 {
 #ifdef HAVE_XKBGETKEYBOARD
@@ -11595,24 +11593,24 @@ syms_of_xfns ()
 
   init_x_parm_symbols ();
 
-  DEFVAR_BOOL ("cross-disabled-images", &cross_disabled_images
-    /* Non-nil means always draw a cross over disabled images.
+  DEFVAR_BOOL ("cross-disabled-images", &cross_disabled_images,
+    doc: /* Non-nil means always draw a cross over disabled images.
 Disabled images are those having an `:conversion disabled' property.
 A cross is always drawn on black & white displays.  */);
   cross_disabled_images = 0;
 
-  DEFVAR_LISP ("x-bitmap-file-path", &Vx_bitmap_file_path
-    /* List of directories to search for bitmap files for X.  */);
+  DEFVAR_LISP ("x-bitmap-file-path", &Vx_bitmap_file_path,
+    doc: /* List of directories to search for bitmap files for X.  */);
   Vx_bitmap_file_path = decode_env_path ((char *) 0, PATH_BITMAPS);
 
-  DEFVAR_LISP ("x-pointer-shape", &Vx_pointer_shape
-    /* The shape of the pointer when over text.
+  DEFVAR_LISP ("x-pointer-shape", &Vx_pointer_shape,
+    doc: /* The shape of the pointer when over text.
 Changing the value does not affect existing frames
 unless you set the mouse color.  */);
   Vx_pointer_shape = Qnil;
 
-  DEFVAR_LISP ("x-resource-name", &Vx_resource_name
-    /* The name Emacs uses to look up X resources.
+  DEFVAR_LISP ("x-resource-name", &Vx_resource_name,
+    doc: /* The name Emacs uses to look up X resources.
 `x-get-resource' uses this as the first component of the instance name
 when requesting resource values.
 Emacs initially sets `x-resource-name' to the name under which Emacs
@@ -11623,8 +11621,8 @@ It may be useful to bind this variable locally around a call
 to `x-get-resource'.  See also the variable `x-resource-class'.  */);
   Vx_resource_name = Qnil;
 
-  DEFVAR_LISP ("x-resource-class", &Vx_resource_class
-    /* The class Emacs uses to look up X resources.
+  DEFVAR_LISP ("x-resource-class", &Vx_resource_class,
+    doc: /* The class Emacs uses to look up X resources.
 `x-get-resource' uses this as the first component of the instance class
 when requesting resource values.
 
@@ -11636,61 +11634,61 @@ is a reasonable practice.  See also the variable `x-resource-name'.  */);
   Vx_resource_class = build_string (EMACS_CLASS);
 
 #if 0 /* This doesn't really do anything.  */
-  DEFVAR_LISP ("x-nontext-pointer-shape", &Vx_nontext_pointer_shape
-    /* The shape of the pointer when not over text.
+  DEFVAR_LISP ("x-nontext-pointer-shape", &Vx_nontext_pointer_shape,
+    doc: /* The shape of the pointer when not over text.
 This variable takes effect when you create a new frame
 or when you set the mouse color.  */);
 #endif
   Vx_nontext_pointer_shape = Qnil;
 
-  DEFVAR_LISP ("x-hourglass-pointer-shape", &Vx_hourglass_pointer_shape
-    /* The shape of the pointer when Emacs is busy.
+  DEFVAR_LISP ("x-hourglass-pointer-shape", &Vx_hourglass_pointer_shape,
+    doc: /* The shape of the pointer when Emacs is busy.
 This variable takes effect when you create a new frame
 or when you set the mouse color.  */);
   Vx_hourglass_pointer_shape = Qnil;
 
-  DEFVAR_BOOL ("display-hourglass", &display_hourglass_p
-    /* Non-zero means Emacs displays an hourglass pointer on window systems.  */);
+  DEFVAR_BOOL ("display-hourglass", &display_hourglass_p,
+    doc: /* Non-zero means Emacs displays an hourglass pointer on window systems.  */);
   display_hourglass_p = 1;
   
-  DEFVAR_LISP ("hourglass-delay", &Vhourglass_delay
-    /* *Seconds to wait before displaying an hourglass pointer.
+  DEFVAR_LISP ("hourglass-delay", &Vhourglass_delay,
+    doc: /* *Seconds to wait before displaying an hourglass pointer.
 Value must be an integer or float.  */);
   Vhourglass_delay = make_number (DEFAULT_HOURGLASS_DELAY);
 
 #if 0 /* This doesn't really do anything.  */
-  DEFVAR_LISP ("x-mode-pointer-shape", &Vx_mode_pointer_shape
-    /* The shape of the pointer when over the mode line.
+  DEFVAR_LISP ("x-mode-pointer-shape", &Vx_mode_pointer_shape,
+    doc: /* The shape of the pointer when over the mode line.
 This variable takes effect when you create a new frame
 or when you set the mouse color.  */);
 #endif
   Vx_mode_pointer_shape = Qnil;
 
   DEFVAR_LISP ("x-sensitive-text-pointer-shape",
-              &Vx_sensitive_text_pointer_shape
-               /* The shape of the pointer when over mouse-sensitive text.
+              &Vx_sensitive_text_pointer_shape,
+               doc: /* The shape of the pointer when over mouse-sensitive text.
 This variable takes effect when you create a new frame
 or when you set the mouse color.  */);
   Vx_sensitive_text_pointer_shape = Qnil;
 
   DEFVAR_LISP ("x-window-horizontal-drag-cursor",
-              &Vx_window_horizontal_drag_shape
-  /* Pointer shape to use for indicating a window can be dragged horizontally.
+              &Vx_window_horizontal_drag_shape,
+  doc: /* Pointer shape to use for indicating a window can be dragged horizontally.
 This variable takes effect when you create a new frame
 or when you set the mouse color.  */);
   Vx_window_horizontal_drag_shape = Qnil;
 
-  DEFVAR_LISP ("x-cursor-fore-pixel", &Vx_cursor_fore_pixel
-    /* A string indicating the foreground color of the cursor box.  */);
+  DEFVAR_LISP ("x-cursor-fore-pixel", &Vx_cursor_fore_pixel,
+    doc: /* A string indicating the foreground color of the cursor box.  */);
   Vx_cursor_fore_pixel = Qnil;
 
-  DEFVAR_LISP ("x-max-tooltip-size", &Vx_max_tooltip_size
-    /* Maximum size for tooltips.  Value is a pair (COLUMNS . ROWS).
+  DEFVAR_LISP ("x-max-tooltip-size", &Vx_max_tooltip_size,
+    doc: /* Maximum size for tooltips.  Value is a pair (COLUMNS . ROWS).
 Text larger than this is clipped.  */);
   Vx_max_tooltip_size = Fcons (make_number (80), make_number (40));
   
-  DEFVAR_LISP ("x-no-window-manager", &Vx_no_window_manager
-    /* Non-nil if no X window manager is in use.
+  DEFVAR_LISP ("x-no-window-manager", &Vx_no_window_manager,
+    doc: /* Non-nil if no X window manager is in use.
 Emacs doesn't try to figure this out; this is always nil
 unless you set it to something else.  */);
   /* We don't have any way to find this out, so set it to nil
@@ -11698,8 +11696,8 @@ unless you set it to something else.  */);
   Vx_no_window_manager = Qnil;
 
   DEFVAR_LISP ("x-pixel-size-width-font-regexp",
-               &Vx_pixel_size_width_font_regexp
-    /* Regexp matching a font name whose width is the same as `PIXEL_SIZE'.
+               &Vx_pixel_size_width_font_regexp,
+    doc: /* Regexp matching a font name whose width is the same as `PIXEL_SIZE'.
 
 Since Emacs gets width of a font matching with this regexp from
 PIXEL_SIZE field of the name, font finding mechanism gets faster for
@@ -11707,8 +11705,8 @@ such a font.  This is especially effective for such large fonts as
 Chinese, Japanese, and Korean.  */);
   Vx_pixel_size_width_font_regexp = Qnil;
 
-  DEFVAR_LISP ("image-cache-eviction-delay", &Vimage_cache_eviction_delay
-    /* Time after which cached images are removed from the cache.
+  DEFVAR_LISP ("image-cache-eviction-delay", &Vimage_cache_eviction_delay,
+    doc: /* Time after which cached images are removed from the cache.
 When an image has not been displayed this many seconds, remove it
 from the image cache.  Value must be an integer or nil with nil
 meaning don't clear the cache.  */);
@@ -11719,8 +11717,8 @@ meaning don't clear the cache.  */);
 #ifdef USE_MOTIF
   Fprovide (intern ("motif"), Qnil);
 
-  DEFVAR_LISP ("motif-version-string", &Vmotif_version_string
-               /* Version info for LessTif/Motif.  */);
+  DEFVAR_LISP ("motif-version-string", &Vmotif_version_string,
+               doc: /* Version info for LessTif/Motif.  */);
   Vmotif_version_string = build_string (XmVERSION_STRING);
 #endif /* USE_MOTIF */
 #endif /* USE_X_TOOLKIT */
diff --git a/src/xmenu.c b/src/xmenu.c
index bf7bdbfd34e..64604eb1e4e 100644
--- a/src/xmenu.c
+++ b/src/xmenu.c
@@ -37,7 +37,7 @@ Boston, MA 02111-1307, USA.  */
 #include <signal.h>
 
 #include <stdio.h>
-#define DOC_STRINGS_IN_COMMENTS
+
 #include "lisp.h"
 #include "termhooks.h"
 #include "keyboard.h"
@@ -656,7 +656,7 @@ list_of_items (pane)
 }
 
 DEFUN ("x-popup-menu", Fx_popup_menu, Sx_popup_menu, 2, 2, 0,
-  /* Pop up a deck-of-cards menu and return user's selection.
+  doc: /* Pop up a deck-of-cards menu and return user's selection.
 POSITION is a position specification.  This is either a mouse button event
 or a list ((XOFFSET YOFFSET) WINDOW)
 where XOFFSET and YOFFSET are positions in pixels from the top left
@@ -688,8 +688,8 @@ in the menu.
 With this form of menu, the return value is VALUE from the chosen item.
 
 If POSITION is nil, don't display the menu at all, just precalculate the
-cached information about equivalent key sequences.  */
-       (position, menu))
+cached information about equivalent key sequences.  */)
+     (position, menu)
      Lisp_Object position, menu;
 {
   Lisp_Object keymap, tem;
@@ -881,7 +881,7 @@ cached information about equivalent key sequences.  */
 #ifdef HAVE_MENUS
 
 DEFUN ("x-popup-dialog", Fx_popup_dialog, Sx_popup_dialog, 2, 2, 0,
-  /* Pop up a dialog box and return user's selection.
+  doc: /* Pop up a dialog box and return user's selection.
 POSITION specifies which frame to use.
 This is normally a mouse button event or a window or frame.
 If POSITION is t, it means to use the frame the mouse is on.
@@ -895,8 +895,8 @@ The return value is VALUE from the chosen item.
 An ITEM may also be just a string--that makes a nonselectable item.
 An ITEM may also be nil--that means to put all preceding items
 on the left of the dialog box and all following items on the right.
-\(By default, approximately half appear on each side.)  */
-       (position, contents))
+\(By default, approximately half appear on each side.)  */)
+     (position, contents)
      Lisp_Object position, contents;
 {
   struct frame * f = NULL;
@@ -2849,8 +2849,8 @@ syms_of_xmenu ()
   Qdebug_on_next_call = intern ("debug-on-next-call");
   staticpro (&Qdebug_on_next_call);
 
-  DEFVAR_LISP ("menu-updating-frame", &Vmenu_updating_frame
-    /* Frame for which we are updating a menu.
+  DEFVAR_LISP ("menu-updating-frame", &Vmenu_updating_frame,
+               doc: /* Frame for which we are updating a menu.
 The enable predicate for a menu command should check this variable.  */);
   Vmenu_updating_frame = Qnil;
 
diff --git a/src/xterm.c b/src/xterm.c
index 492966253de..7215650534c 100644
--- a/src/xterm.c
+++ b/src/xterm.c
@@ -32,7 +32,6 @@ Boston, MA 02111-1307, USA.  */
 
 #ifdef HAVE_X_WINDOWS
 
-#define DOC_STRINGS_IN_COMMENTS
 #include "lisp.h"
 #include "blockinput.h"
 
@@ -14799,22 +14798,22 @@ syms_of_xterm ()
   staticpro (&previous_help_echo);
   help_echo_pos = -1;
 
-  DEFVAR_BOOL ("x-stretch-cursor", &x_stretch_cursor_p
-    /* *Non-nil means draw block cursor as wide as the glyph under it.
+  DEFVAR_BOOL ("x-stretch-cursor", &x_stretch_cursor_p,
+    doc: /* *Non-nil means draw block cursor as wide as the glyph under it.
 For example, if a block cursor is over a tab, it will be drawn as
 wide as that tab on the display.  */);
   x_stretch_cursor_p = 0;
 
   DEFVAR_BOOL ("x-use-underline-position-properties",
-               &x_use_underline_position_properties
-     /* *Non-nil means make use of UNDERLINE_POSITION font properties.
+               &x_use_underline_position_properties,
+     doc: /* *Non-nil means make use of UNDERLINE_POSITION font properties.
 Nil means ignore them.  If you encounter fonts with bogus
 UNDERLINE_POSITION font properties, for example 7x13 on XFree prior
 to 4.1, set this to nil.  */);
   x_use_underline_position_properties = 1;
 
-  DEFVAR_LISP ("x-toolkit-scroll-bars", &Vx_toolkit_scroll_bars
-    /* What X toolkit scroll bars Emacs uses.
+  DEFVAR_LISP ("x-toolkit-scroll-bars", &Vx_toolkit_scroll_bars,
+    doc: /* What X toolkit scroll bars Emacs uses.
 A value of nil means Emacs doesn't use X toolkit scroll bars.
 Otherwise, value is a symbol describing the X toolkit.  */);
 #ifdef USE_TOOLKIT_SCROLL_BARS