Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
The community reviewed whether to reopen this question last month and left it closed:
Original close reason(s) were not resolved
Improve this question
I am currently writing a Bash script that has a number of functions in it and would like to add docs to make other team members understand what the point of the function is.
Is there a standard "style" for documenting Bash scripts and the functions it contains?
I do understand I'm adding an answer to an old question, but I feel the tooling has improved lately and would like to give additional suggestions in order to help out others who are viewing this question.
I have recently found TomDoc.sh, which uses TomDoc style comments in shell scripts. The tool provided can then extract information and generate markdown or plain text documents.
Other tools also exist. BashDoc is modeled after the JavaDoc syntax, supporting a variety of tags. With RoboDoc you embed a C-style comment in your Bash code and it extracts the necessary information. Lastly, Apple uses HeaderDoc for its shell scripting. All three of these have a suggested style for the comments that you write.
If you wish to annotate your code more than generate documentation, shocco.sh may be what you'd prefer. It doesn't have a specific format and is designed for you to see human-readable text describing the shell commands that you are running.
Usually, I try to follow guidelines that are analog to the ones I use with other languages like C.
This includes a function header containing:
function name, short description and purpose
list of arguments and return values, with descriptions
list of all side effects (e.g., changes in variables or files)
To my understanding there is no standard for Bash doc.
But typically you would:
include a header to your bash file, with your name, copyright,
contact, and briefly what the script does
a usage() function that
explains how to launch and use your function.
a comment at the top of
each function to explain what the func does.
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 1 year ago.
Improve this question
I want to create a new vim syntax checker for a new programming language that is not used widely, first i tried to read the code of the follwing plugins neomake, syntastic
, and Ale in order to understand how i can build my own syntax checker plugin but i could not really get it
so i just want know what is the best and easy way to create syntax checker plugin for vim
I am not sure what you are asking for, here.
At a very high level, linting works like this:
you pass a file to some program or some code via stdin,
the program analyses the code in the file,
the program outputs nothing if the code is correct or a list of errors if the code is incorrect.
For example, assuming our linter is called mylinter:
$ mylinter file_with_correct_code.foo
<nothing>
$ mylinter file_with_erroneous_code.foo
/path/to/file_with_erroneous_code.foo:12:23: missing semicolon
No one knows anything about your language or compiler so you are the only one who can tell if and how your compiler can be used as described above, which is a prerequisite for Vim integration.
How to integrate it in Vim is the next step, and it is entirely dependent on those informations, which you failed to provide.
So…
Figure out if/how your compiler can be used that way.
We can't do that for you.
Read the help section I already pointed to in the comments: :help write-compiler-plugin to know how to integrate your linter in Vim the vanilla way or the relevant sections of the plugins you want to integrate with.
We may be able to help with specific issues.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 4 years ago.
Improve this question
I'm aware that the general convention is that short flags (or single dash "-") is followed by a single character, and long flags (or double dash "--") is followed by multiple characters (usually an English word). Also, sometimes multiple short flags can be written like this as shorthand ("-l -c" as "-lc").
However, is this also valid "--c"? It seems to be breaking the aforementioned convention but is it fine as long is it's a unique flag identifier?
Tried searching the web but wasn't able to find any results on this.
Yes, as a general rule, neither your shell nor your kernel cares about the format of the arguments you pass to your command, as long as the program you're writing expects that format.
However, if by "can" you mean "does that respect the POSIX conventions of command arguments", then you should look at the Utility conventions part of the POSIX standard. In the last published version, there is no particular restriction against what you want here, therefore you should be fine.
That said, when you write programs for other people, try to apply the Principle of least astonishment. People usually expect single letter commands to be preceded by a -, so it is a good practice to follow the de-facto conventions when possible.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 7 years ago.
Improve this question
I'm looking for a way to correct bash commands if they have been misspelled.
Let's say you have installed a program called "FooBar" but you type "foobar" (or foo bar or FOOBAR or foebar) in your shell. Is there any way to check if something similar to what you are looking for exists in your PATH?
I'm thinking about writing a bash script that normalizes user input and uses the Levenshtein distance algorithm to check what they have typed against anything in PATH. But maybe there's already something is written out there or a better way to accomplish this task.
Any suggestions?
If you problem is case-sensitivity only, then you can switch this off in the readline configuration by the following:
echo "set completion-ignore-case On" >> ~/.inputrc
However, if you are seeking for some clever mechanism to execute similar commands (by using fuzzy logic for example) I'll not recommend to use such tool in a command-line since it could be very dangerous.
Imagine what could happen for example in commands like rmv? is it rm or mv? .. only the user can answer this question.
Note: This may be useful if you are running a Cygwin env where case-sensitivity is not a problem. In Linux commands are case sensitive. So switching this functionality off is not a good idea.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
Do you know any editor for man(1) pages which work on text screen (terminal and console)? Searching the interned did not gave any useful results as the words are very common.
Or should I learn the details of the format and write it by hand?
You can write it e.g. in markdown then convert it via e.g. pandoc to manpage format ((t|g)roff). Here is the fine manual: http://johnmacfarlane.net/pandoc/README.html .
HTH
Sure, go ahead and learn the format and write it by hand in a regular text editor.
On the other hand, the perl project uses a kind of universal markup called pod and then converts into manpages by running pod2man.
Man pages are written in plain text with a simple markup language called troff.
Actually there are several related markup systems all supported by a set of commands ending in roff: nroff, troff, and the all singing, all dancing super-set groff.
My Mac OS 10.5 systems has a nice summary of the history in man 7 roff.
As others have noted there are several tools around which can convert other markup formats to man pages.
The easiest way is to write content as "reStructuredText" (simpler than wiki syntax) and use docutils to generate manpage from it.
See this tutorial.
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 5 years ago.
Improve this question
VBA solutions can vary widely in size.
I would like to add user help documentation to all solutions but the level of effort to create and deploy the help needs to match the size of the solution.
You should check the VBA version of MZ-Tools. It is an add-in for VBA that can automatically generate documentation from your code (function name, parameters, comments, subject, etc.). You can also use it to automatically generate line numbers, onError labels, etc. More on the automatic documenting feature can be found here.
It is free, easy, and very efficient. Once you notice how much you save time by using it, please do like me: donate.
You may wish to consider HTML Help. It allows you to produce help files that are similar to standard Microsoft help. It is not particularly difficult to use, for the most part.