4.2.12 Index-Entry Descriptions

► |  | Scribble: The Racket Documentation Tool

1 | Getting Started
2 | @ Syntax
3 | High-Level Scribble API
4 | Scribbling Documentation
5 | Literate Programming
6 | Low-Level Scribble API
7 | Running scribble
| Index

► | 4 | Scribbling Documentation

4.1 | Getting Started with Documentation
4.2 | Manual Forms
4.3 | Racket
4.4 | Evaluation and Examples
4.5 | In-Source Documentation
4.6 | BNF Grammars
4.7 | Compatibility Libraries

▼ | 4.2 | Manual Forms

4.2.1 | Typesetting Code
4.2.2 | Documenting Modules
4.2.3 | Documenting Forms, Functions, Structure Types, and Values
4.2.4 | Documenting Classes and Interfaces
4.2.5 | Documenting Signatures
4.2.6 | Various String Forms
4.2.7 | Links
4.2.8 | Indexing
4.2.9 | Bibliography
4.2.10 | Version History
4.2.11 | Miscellaneous
4.2.12 | Index-Entry Descriptions
4.2.13 | Manual Rendering Style

On this page:

index-desc
desc-extras/ c
module-path-index-desc
language-index-desc
reader-index-desc
exported-index-desc
exported-index-desc*
form-index-desc
procedure-index-desc
thing-index-desc
struct-index-desc
class-index-desc
interface-index-desc
mixin-index-desc
method-index-desc
constructor-index-desc

Racket
top contents ← prev up next →

#### 4.2.12 Index-Entry Descriptions🔗ℹ

(require scribble/manual-struct) | package: scribble-lib

The scribble/manual-struct library provides types used to describe index entries created by scribble/manual functions. These structure types are provided separate from scribble/manual so that scribble/manual need not be loaded when deserializing cross-reference information that was generated by a previously rendered document.

> > struct
> > (struct |  | index-desc (extras)
> #:extra-constructor-name make-index-desc)
> extras : desc-extras/c
> value desc-extras/c : contract?

Provides optional information about an index entry through an extras hash table. All values in the hash table should be writeable in the sense that read will reconstruct the value. Any symbol is allowed as a key in extras, but some are well-known:

- 'language-family: A list strings describing language families for which this entry is relevant. If this key is missing, the default language-family list is '("Racket").

- 'sort-order: A real number that is used to order this entry with respect to others that have the same key. Smaller values of 'sort-order are shown before later values, and the default is 0.

- 'kind: A string describing the binding’s category, such as "procedure" or "class". Like most other values in extras, this string is not added to the index entry’s main text as shown to a user, but it may be rendered by some interfaces, such as to the side or in hover text.

- 'module-kind: A symbol indicating an entry for a module as documented with defmodule, where the symbol is 'lang for a module documented with #:lang, 'reader for a module documented with #:reader, and 'lib otherwise.

- 'part?: A boolean indicating whether the index entry describes a section within a document.

- 'hidden?: A boolean indicating that the index entry describes a binding that is covered from a user’s perspective by a different index entry. These are considered redundant and filtered from index rendering.

When index entries are recorded, the entry’s extras table can receive additional key–value mappings via part context using the 'index-extras key. See index-element for more information.

The desc-extras/c contract is equivalent to

> (hash/dc [k symbol?]
> [v (k)
> (case k
> [(language-family) (listof string?)]
> [(sort-order) real?]
> [(kind) string?]
> [(module-kind) (or/c 'lib 'lang 'reader)]
> [(part?) boolean?]
> [(hidden?) boolean?]
> [else any/c])]
> #:immutable #t)

The index-desc struct is preferable over other index entry descriptions below, except for exported-index-desc and exported-index-desc*.

Added in version 1.54 of package scribble-lib.

> > struct
> > (struct |  | module-path-index-desc ()
> #:extra-constructor-name make-module-path-index-desc)

> NOTE: This struct is deprecated; use index-desc, instead.

Indicates that the index entry corresponds to a module definition via defmodule and company.

> > struct
> > (struct |  | language-index-desc module-path-index-desc ()
> #:extra-constructor-name make-language-index-desc)
> > struct
> > (struct |  | reader-index-desc module-path-index-desc ()
> #:extra-constructor-name make-reader-index-desc)

> NOTE: This struct is deprecated; use index-desc, instead.

Indicates that the index entry corresponds to a module definition via defmodule with the #:lang or #:reader option. For example, a module definition via defmodulelang has a language-index-desc index entry and a module definition via defmodulereader has a reader-index-desc index entry.

> > struct
> > (struct |  | exported-index-desc (name from-libs)
> #:extra-constructor-name make-exported-index-desc)
> name : symbol?
> from-libs : (listof module-path?)

Indicates that the index entry corresponds to the definition of an exported binding. The name field and from-libs list correspond to the documented name of the binding and the primary modules that export the documented name (but this list is not exhaustive, because new modules can re-export the binding).

> > struct
> > (struct |  | exported-index-desc* exported-index-desc (extras)
> #:extra-constructor-name make-exported-index-desc*)
> | extras |  | : |  |
> (and/c desc-extras/c
> (hash/dc [k symbol?]
> [v (k)
> (case k
> [(display-from-libs) (listof content?)]
> [(method-name) symbol?]
> [(constructor?) boolean?]
> [(class-tag) tag?]
> [(long-key) string?]
> [else any/c])]
> #:immutable #t))

Like exported-index-desc, but with additional optional information in an extras hash table like index-desc. Some additional keys are well-known:

- 'display-from-libs: A list of content in parallel to the from-libs field that renders the exporting library in the module’s language’s native form.

- 'method-name: A symbol indicating that the index entry describes a method for the class that is in the name field, and the symbol is the method’s name.

- 'constructor?: A boolean indicating that the index entry describes a class’s constructor, separate from an index entry for the class. A constructor normally also has 'hidden? as true.

- 'class-tag: A tag that links to the class’s main entry in the case of a method or constructor index entry, where the name field has the class name in both cases.

- 'long-key: An alternative string for searches to match. This string is useful when the name that is normally used to refer to a binding has an extra prefix that is added on import, for example.

The exported-index-desc* struct is preferable over other index entry descriptions below.

Added in version 1.53 of package scribble-lib.
Changed in version 1.59: Added 'long-key.

> > struct
> > (struct |  | form-index-desc exported-index-desc ()
> #:extra-constructor-name make-form-index-desc)

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to the definition of a syntactic form via defform and company.

> > struct
> > (struct |  | procedure-index-desc exported-index-desc ()
> #:extra-constructor-name make-procedure-index-desc)

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to the definition of a procedure binding via defproc and company.

> > struct
> > (struct |  | thing-index-desc exported-index-desc ()
> #:extra-constructor-name make-thing-index-desc)

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to the definition of a binding via defthing and company.

> > struct
> > (struct |  | struct-index-desc exported-index-desc ()
> #:extra-constructor-name make-struct-index-desc)

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to the definition of a structure type via defstruct and company.

> > struct
> > (struct |  | class-index-desc exported-index-desc ()
> #:extra-constructor-name make-class-index-desc)

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to the definition of a class via defclass and company.

> > struct
> > (struct |  | interface-index-desc exported-index-desc ()
> #:extra-constructor-name make-interface-index-desc)

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to the definition of an interface via definterface and company.

> > struct
> > (struct |  | mixin-index-desc exported-index-desc ()
> #:extra-constructor-name make-mixin-index-desc)

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to the definition of a mixin via defmixin and company.

> > struct
> > (struct |  | method-index-desc exported-index-desc | ( | method-name
> > |  |  |  | class-tag)
> #:extra-constructor-name make-method-index-desc)
> method-name : symbol?
> class-tag : tag?

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to the definition of an method via defmethod and company. The name field from exported-index-desc names the class or interface that contains the method. The method-name field names the method. The class-tag field provides a pointer to the start of the documentation for the method’s class or interface.

> > struct
> > (struct |  | constructor-index-desc exported-index-desc (class-tag)
> #:extra-constructor-name make-constructor-index-desc)
> class-tag : tag?

> NOTE: This struct is deprecated; use exported-index-desc*, instead.

Indicates that the index entry corresponds to a constructor via defconstructor and company. The name field from exported-index-desc names the class or interface that contains the method. The class-tag field provides a pointer to the start of the documentation for the method’s class or interface.

top contents ← prev up next →