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.
Related
I'm cross-compling with mingw and got this error:
undefined reference to `rpl_realloc'
After some searching I found this can be resolved as follows in configure.ac or as environment variables set prior to calling ./mingw64-configure:
ac_cv_func_malloc_0_nonnull=yes
ac_cv_func_realloc_0_nonnull=yes
What defines these macros, and as there any documentation on the subject? I couldn't find any...
What defines these macros, and as there any documentation on the subject?
Autoconf uses the ac_cv_ prefix for its "cache variables", in which it records the results of configuration tests it has performed. In the event that the same check is requested multiple times, these allow it to use the previously-determined result instead of performing the check again.
The general naming convention for these is documented in the Autoconf manual. The particular cache variable names you ask about are documented to cache the results of the Autoconf's AC_FUNC_MALLOC and AC_FUNC_REALLOC macros, respectively. That documentation also speaks to the rpl_realloc name.
It is allowed to use these variables in configure.ac to programmatically determine the results of those checks, but it is a relatively nasty hack to assign values to those variables directly. In this particular case, however, the error suggests that whoever prepared the autotooling for the project you're trying to build did a sloppy job of it. If fudging the cache variables gets you a successful build and a working program then that's a tempting and much easier alternative to actually fixing the project.
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.
For instance, I saw the following line the other day:
#define ATS_STATIC_PREFIX "_Game_of_24_"
What is the meaning of such a line? What purpose does it serve?
Its literally one search on the google.
Here is the site.
Here is the quoted answer for your question:
When the DATS-file is
compiled into C, the prefix 'foo__' is attached to the original names
of static variables and functions in the generated C code.
This feature can be very useful if one wants to mix the C code
generated from multiple ATS source files as doing so is likely to
result in name conflicts among static variables and functions in the
C code. Such conflicts can be resolved by properly setting
ATS_STATIC_PREFIX. The same applies to loading PHP code generated from
ATS source.
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"
So, I'm building a custom backend for GCC for a processor. This processor has 4 address spaces: local, global, mmm, and mmr. I want to make it such that when writing c code, you can do this:
int global x = 5;
which would cause the compiler to spit out an instruction like this:
ldi.g %reg, 5
I know that certain processors like blackfin and MeP do something similar to this, so I figure its possible to do, however I have no idea how to do it. The technique that should allow me to do this is a variable attribute.
Any suggestions on how I could go about doing this?
You can add target-specific attributes by registering a struct attribute_spec table using TARGET_ATTRIBUTE_TABLE, as described in the GCC internals documentation. The details of struct attribute_spec can be found in the source (gcc/tree.h).
This handler doesn't need to do anything beyond returning NULL_TREE, although typically it will at least do some error checking. (Read the comments in gcc/tree.h, and look at examples in other targets.)
Later, you can obtain the list of attributes for a declaration tree node with DECL_ATTRIBUTES() (see the internals docs again), and use lookup_attribute() (see gcc/tree.h again) to see if a given attribute in the list.
You want to references to a symbol to generate different assembly based on your new attributes, so you probably want to use the TARGET_ENCODE_SECTION_INFO hook ("Define this hook if references to a symbol or a constant must be treated differently depending on something about the variable or function named by the symbol") to set a flag on the symbol_ref (as the docs suggest). You can define a predicate for testing this flag in the .md .