The example Reference Manual

Table of Contents

The example Reference Manual

This is the example Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Jan 25 10:54:41 2021 GMT+0.

Copyright © 2021 Alexander Artemenko

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled “Copying” is included exactly as in the original.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be translated as well.

Copying

Permission to use, copy, modify, and distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

1 Introduction

This is the introduction to Declt example project. Declt is a documentation system used to build a Quickref — API reference for all libraries, included into the Quicklisp.

This project is a part of the CL Doc Systems — attempt to create a comprehensive set of examples of different Common Lisp documentation systems.

1.1 Pros & Cons

1.1.1 Pros

• Generates manuals in Texinfo which can be converted to HTML, PDF, DVI and PostScript. Here is PDF version of this site.
• Automatically embeds license information.
• Uses standard Texinfo format, which has good documentation. Theoretically, Texinfo should well suite for large documents.
• It is able to generate single or multi page HTML output. To switch the mode, change single-page-p variable in docs/scripts/builder.lisp.

1.1.2 Cons

• Works only under SBCL.
• Free form documentation chapters are limited by "Introduction" and "Conclusion".
• Texinfo is not so popular these days. Also, it is very verbose.
• There is no default CSS theme.
• I wasn’t able to use cross referencing Texinfo tags from docstrings. Seems Texinfo markup does not work there. But it works in the introduction and conclusion. Here is example link to the do-the-job function.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 example

Author

Alexander Artemenko

License

MIT

Description

This description will be used only if long-description is missing

Long Description

Test long description. Both descriptions will be shown in the docs.

Dependency

example/app (system)

Source

example.asd (file)

Directory

/home/runner/work/declt/declt/

2.2 example/app

Author

Alexander Artemenko

License

MIT

Dependencies

• example/utils (system)
• example/class (system)

Source

example.asd (file)

Directory

/home/runner/work/declt/declt/

Component

file-type.lisp (file)

2.3 example/utils

Author

Alexander Artemenko

License

MIT

Source

example.asd (file)

Directory

/home/runner/work/declt/declt/

Component

file-type.lisp (file)

2.4 example/class

Author

Alexander Artemenko

License

MIT

Source

example.asd (file)

Directory

/home/runner/work/declt/declt/

Component

file-type.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 example.asd

Location

/home/runner/work/declt/declt/example.asd

Systems

• example (system)
• example/app (system)
• example/utils (system)
• example/class (system)

3.1.2 example/app/file-type.lisp

Parent

example/app (system)

Location

app.lisp

Packages

example/app

Exported Definitions

foo (function)

3.1.3 example/utils/file-type.lisp

Parent

example/utils (system)

Location

utils.lisp

Packages

example/utils

Exported Definitions

do-the-job (function)

Internal Definitions

concat (function)

3.1.4 example/class/file-type.lisp

Parent

example/class (system)

Location

class.lisp

Packages

example/class

Exported Definitions

• admin (class)
• non-documented-user (class)
• user (class)

Internal Definitions

• email (method)
• inner-documented-user (class)
• is-admin (generic function)
• is-admin (method)
• is-admin (method)
• last-login-at (method)
• (setf last-login-at) (method)
• name (method)

4 Packages

Packages are listed by definition order.

4.1 example/app

This is docstring for the EXAMPLE/APP package.

The package contains a FOO function which does it’s job by applying transformation to the first and second arguments.

Source

file-type.lisp (file)

Use List

common-lisp

Exported Definitions

foo (function)

4.2 example/utils

The utils package.

The only exported function DO-THE-JOB will be show in a separate section "Exported Definitions".

Source

file-type.lisp (file)

Use List

common-lisp

Exported Definitions

do-the-job (function)

Internal Definitions

concat (function)

4.3 example/class

This package demonstrates how Declt displays classes and generic functions.

The key consept is USER class

It is possible to check if user has admin privileges, using this IS-ADMIN function.

Right now, IS-ADMIN returns T only for objects of class ADMIN.

Source

file-type.lisp (file)

Use List

common-lisp

Exported Definitions

• admin (class)
• non-documented-user (class)
• user (class)

Internal Definitions

• email (generic function)
• email (method)
• inner-documented-user (class)
• is-admin (generic function)
• is-admin (method)
• is-admin (method)
• last-login-at (generic function)
• last-login-at (method)
• (setf last-login-at) (method)
• (setf last-login-at) (generic function)
• name (generic function)
• name (method)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Functions

Function: do-the-job FIRST SECOND

The function does the job.

It CONCATENATES first and second arguments
calling internal function concat.

On this multiline we’ll check how does documentation system processes docstrings.

NOTE: pay attention the Texinfo markup in the second paragraph does not supported in docstrings and I was not able to make CONCATENATES word bold :(

Package

example/utils

Source

file-type.lisp (file)

Function: foo FIRST &key OTHER

This is example function.

* FIRST - Just a first argument.
* OTHER - Optional keyword argument. Default is 100500.

Returns: A string with first and other concatenated.

Internally it calls EXAMPLE/UTILS:DO-THE-JOB
to do the real job.

Note, that the link above is broken, but Coo does not warn us when building the docs. Sphinx issues a warning inn such case.

Package

example/app

Source

file-type.lisp (file)

5.1.2 Classes

Class: admin ()

Admins should have additional priveleges.

Package

example/class

Source

file-type.lisp (file)

Direct superclasses

user (class)

Direct methods

is-admin (method)

Class: non-documented-user ()

Package

example/class

Source

file-type.lisp (file)

Direct superclasses

user (class)

Class: user ()

All users in the system have this class.

Last login slot is updated automatically.

Package

example/class

Source

file-type.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

• admin (class)
• non-documented-user (class)
• inner-documented-user (class)

Direct methods

• is-admin (method)
• last-login-at (method)
• last-login-at (method)
• email (method)
• name (method)

Direct slots

Slot: name

A full username.

Type

string

Initargs

:name

Readers

name (generic function)

Slot: email

Correct email address.

Type

string

Initargs

:email

Readers

email (generic function)

Slot: last-login-at

Readers

last-login-at (generic function)

Writers

(setf last-login-at) (generic function)

5.2 Internal definitions

5.2.1 Functions

Function: concat FIRST SECOND

This function is not exported and should not be showed in the API reference.

Package

example/utils

Source

file-type.lisp (file)

5.2.2 Generic functions

Generic Function: email OBJECT

Package

example/class

Methods

Method: email (USER user)

Correct email address.

Source

file-type.lisp (file)

Generic Function: is-admin USER

Returns t if user can modify the system.

Package

example/class

Source

file-type.lisp (file)

Methods

Method: is-admin (USER admin)

Method: is-admin (USER user)

Generic Function: last-login-at OBJECT

Generic Function: (setf last-login-at) NEW-VALUE OBJECT

Package

example/class

Methods

Method: last-login-at (USER user)

automatically generated reader method

Source

file-type.lisp (file)

Method: (setf last-login-at) NEW-VALUE (USER user)

automatically generated writer method

Source

file-type.lisp (file)

Generic Function: name OBJECT

Package

example/class

Methods

Method: name (USER user)

A full username.

Source

file-type.lisp (file)

5.2.3 Classes

Class: inner-documented-user ()

This class only to demostrate how Declt’s separates exported symbols from internal.

It will not be shown in the separate section "Internal Definitions".

Package

example/class

Source

file-type.lisp (file)

Direct superclasses

user (class)

6 Conclusion

Declt can be used be used when you need to generate API reference for third-party libraries as Quickref does for all Quicklisp libraries.

Ability to generate docs in different formats also might be interesting.

But the lack of markup support for docstrings and cross-reference helpers along with limited ability to create free form documentation chapters makes Declt useless for documenting 40Ants projects.

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types