I have Googled a handful of things such as "lisp documentation strings", "lisp comments", and a few others and I cant find anything that specifically addresses this.
I see a lot of code (especially in CL and elisp) that looks like
(defvar test 1
"This is a quoted string and it says things"
)
Where I would normally do
; This is a comment
(defvar test 1)
Which is preferred? Do each serve a different purpose? Thanks!
Many objects in Common Lisp can have a documentation string, that can be retrieved with the generic function documentation and set with the generic function (setf documentation). According to the specification:
Documentation strings are made available for debugging purposes. Conforming programs are permitted to use documentation strings when they are present, but should not depend for their correct behavior on the presence of those documentation strings. An implementation is permitted to discard documentation strings at any time for implementation-defined reasons.
So the first case allows the definition of a variable together with its documentation string, that can be used to store at run-time, if the implementation permits so, information useful for documentation and debugging purposes, either used through the IDE, or directly, through a form like:
(documentation 'test 'variable)
The second case, instead, is just a comment inside a source file, useful only for human consumption, and it is completely ignored by the reader/compiler of the system.
Development environments will use these documentation features. For example GNU Emacs / SLIME:
Move the text cursor onto the symbol test.
Type c-c c-d c-d (Describe Symbol).
Now SLIME displays a buffer with the following content:
COMMON-LISP-USER::TEST
[symbol]
TEST names a special variable:
Value: 1
Documentation:
This is a quoted string and it says things
A simple comment in the source code won't enable this form of development environment integration and documentation lookup.
I saw your tag included scheme and elisp as well. In CL and Elisp always use docstrings. They are used by documentation systems in their languages. Scheme does not have that feature so you will have to continue using comments to document functions.
Did't you try to see hyperspec for defvar?
defvar takes an optional argument - document string, and this is what are you talking about.
Documentation specified this way can be acessed throug documentation:
CL-USER> (defvar *a* "A variable" "A docstring")
*A*
CL-USER> (documentation '*a* 'variable)
"A docstring"
Related
When I run raku --doc test.raku on the following code:
#! /usr/bin/env raku
use v6.d;
#| The answer
my Int $bar = 42;
#= Thank you, Douglas
say $bar.WHY.leading;
say $bar.WHY.following;
I get no output. When I run the code (raku test.raku), the output is:
Nil
Nil
Is there any way to use Declarator Blocks with variables?
It is syntactically valid to place a declarator comment anywhere; one can even put it on a statement:
#| Look, a statement
say "hello";
Rakudo will currently only attach the documentation to packages, attributes, routines, and parameters, since these have meta-objects that have a means to attach documentation.
By contrast, the Comma IDE also keeps track of documentation comments on variables, and can show them at usage sites of the variable:
An IDE keeping track of them is quite different from a Rakudo implementation making them available at runtime, however.
If declarator comments were to work on variables, almost certainly one would have to write:
say $bar.VAR.WHY.leading;
Because otherwise one would be talking about what is in the variable, not the Scalar (or Array or Hash) container itself. Even then, if one binds:
#| The answer
my Int $bar := 42;
Then there isn't a container to attach the documentation to, so there's no way to make it accessible at runtime.
The upcoming RakuAST (a standardized document object model for Raku code) would allow an opportunity to provide access to declarator docs attached to anything whatsoever (although it doesn't yet); this would still not provide runtime access to the docs, but it would provide a means for tools to parse and extract them.
I'm maintaining some code written using Go (golang), Viper and Cobra.
On one line, it has:
rootCmd.PersistentFlags().String("cfg", "", "A description")
And then on the following line it has
rootCmd.PersistentFlags().StringP("output", "o", ".", "Another description")
What is the difference between String and StringP in this context?
Looking at example usages in various tutorials, there seem to be P and non-P versions of various methods, such as StringVarP and StringVar.
What is the difference between these versions? What is the significance of the P?
Is there a way I can tell whether a given method has a P or non-P counterpart?
Search engines tend to take me to cobra or viper tutorial pages, which make use of these methods without explaining the P or non-P counterpart.
I found some material on pflags which suggested it might be to do with whether the parameter has a short (one-letter) form. Could this be it?
Post-edit note: Having received answers to this question, it seems spf13/pflag is indeed used under the hood by the above mentioned golang frameworks. However, it's not immediately clear that one should go looking through the pflags documentation when using cobra or viper.
As this is a Q&A site, I've reverted an edit that removed many of the keywords I would have entered when looking for this answer, as I feel others looking for the same information will be better served that way.
The P suffix denotes a function that accepts a single letter flag name in addition to the full name, as documented in the usage section of the pflag docs:
The pflag package also defines some new functions that are not in
flag, that give one-letter shorthands for flags. You can use these by
appending 'P' to the name of any function that defines a flag.
To answer your individual questions:
what's the difference: the P functions take an extra parameter: the single letter name. This short flag can be used with a single -.
which methods have a P counterpart: all of them, as can be seen in the pflag reference
As for why this is documented in pflag and not viper or cobra, this is because both viper and cobra use the pflag library.
Is it possible to write documentation in source files like in Common Lisp or Go, for example, and extract it from source files? Or everybody uses Scribble to document their code?
The short answer is you can write in-source documentation by using scribble/srcdoc.
Unlike the other languages you mentioned, these aren't "doc strings":
Although you can write plain text, you have full Racket at-expressions and may use scribble/manual forms and functions.
Not only does this allow for "richer" documentation, the documentation goes into its own documentation submodule -- similar to how you can put tests into test submodules. This means the documentation or tests add no runtime overhead.
You do need one .scrbl file, in which you use scribble/extract to include the documentation submodule(s). However you probably want such a file, anyway, for non-function-specific documentation (topics such as introduction, installation, or "user's guide" prose as opposed to "reference" style documentation).
Of course you can define your own syntax to wrap scribble/srcdoc. For example, in one project I defined a little define/doc macro, which expands into proc-doc/names as well as a (module+ test ___) form. That way, doc examples can also be used as unit tests.
How Racket handles in-source documentation intersects a few interesting aspects of Racket:
Submodules let you define things like "test-time" and "doc-time" as well as run-time.
At-expressions are a different syntax for s-expressions, especially good when writing text.
Scribble is an example of using a custom language -- documentation-as-a-program -- demonstrating Racket's ability to be not just a programming language, but a programming-language programming language.
Recently I have been reviewing a lot of Ansible modules(code) and I have come across some with this strange nomenclature in the documentation section when referring to arguments such as the examples (F5 modules) below:
specified, the default of C(round-robin) will be used
or this
If this value is an IP address, and the C(type) is C(tcp) (the
default),
then a C(port) number must be specified.
What is the C and is it required when documenting your code? As I said not all of the modules have in them.
I just found this in ansible.docs-1.7.pdf1), page 545:
The description, and notes fields support formatting with some
special macros.
These formatting functions are U(), M(), I(), and C() for URL,
module, italic, and constant-width respectively. It is suggested to
use C() for file and option names, and I() when referencing
parameters; module names should be specifies as M(module).
1) This seems to be somewhat dated, but should still be valid. The same can also be found in the latest online documentation.
(show-data 'YHOO :config 'my-config)
I saw some Scheme code (in Guile) like the line above and get confused with the colon syntax :config .
What kind of language features of this? Is it a intrinsic feature of Scheme, or specially designed for the Guile lib? How does it work? I kept searching this online but still found nothing. Thanks.
It's a keyword and its purpose is to make the invocation of a procedure that receives optional arguments easier and convenient.
You can read more about this feature in this section of the Guile Reference Manual.