Documentation that focuses on code itself, such as its function, correct use, expected output, relationship to other code as well as database and tables connections, and usage examples.
Questions tagged [code-documentation]
381 questions
5
votes
3 answers
Is there any offline javascript API document tool available like YARD for ruby does?
Mozilla online documentation are great, but sometimes I don't have the internet connection and reference in the o'reilly javascript definitive guide is also great but lack of the handy searchable capability.
I just wonder if there anything for…
mko
- 21,334
- 49
- 130
- 191
5
votes
2 answers
What's the best way to handle/format Javadoc and annotations in code?
I've looked across this forum, and I've googled this one, and I'm not sure what is the best way to handle Javadoc and annotations that appear together in the same class.
From what I can see from Sun/Oracle's documentation, they seem to suggest…
Chris Aldrich
- 1,904
- 1
- 22
- 37
5
votes
0 answers
KDoc Annotations not rendered in Dokka generated HTML
I am currently testing the Dokka documentation and some of the annotations I have made are not being rendered. Here are my findings:
Classes don't show @sample, and html tags , : See SimpleCalculator class documentation
If a…
Paula Kristin
- 813
- 2
- 11
- 27
5
votes
2 answers
What's the standard way to document a namedtuple?
Looking to clean up some code by using a namedtuple to hold multiple variables for passing through a number of functions. Below is a simplified example (I actually have a few more additional arguments).
Before:
def my_function(session_cass,…
latetojoin
- 113
- 1
- 8
5
votes
1 answer
Is there a way to attach a Javadoc doc comment to a Groovy script?
For a Groovy or Java class or method, I would generally include any API-level documentation in a doc comment (aka Javadoc comment), rather than a regular comment. What is the analogous way of adding such comments about a Groovy script?
I personally…
M. Justin
- 14,487
- 7
- 91
- 130
5
votes
2 answers
Adding sub-properties to an existing property-list in jsdoc
I am trying to automate a particular module in our JS library and am stuck at a point where I want to define a set of properties (lets say an object that goes as construction parameter of a class).
/**
* This function initiates world peace!
*…
Shamasis Bhattacharya
- 3,392
- 3
- 20
- 24
5
votes
4 answers
Python headers -- What is the purpose of the $ ( dollar sign ) encapsulation?
Apologies in advance, this is something that I really figured I could find on the web, but I was having troubles.
In Python, in the header portion, I see that sometimes people will wrap their literals with a dollar sign ( $ ). It seems, judging…
Mike Williamson
- 4,915
- 14
- 67
- 104
5
votes
2 answers
Installing manually PHPDocumentor on Mac
After trying to install PHPDocumentor with PEAR install with no success, i tried it manually as is detailed on the official website: http://www.phpdoc.org/docs/latest/for-users/installation.html
I downloaded the files and i make an alias on…
Alvaro
- 40,778
- 30
- 164
- 336
4
votes
1 answer
Autogenerate Console Output for Roxygen @examples Section
Background
I am documenting an R package, and I wish the @examples section(s) to include the (commented) output below the code, so the user need not run the examples (in the console, etc.) in order to see the output.
As such, I have typed the output…
Greg
- 3,054
- 6
- 27
4
votes
2 answers
Extending class documentation and live templates
I am playing with code documentation and live templates and I quite don't get it.
I've read Dr.Bob's article about generating documentation and wiki articles about live templates but I have one problem with class description.
By class description I…
Wodzu
- 6,932
- 10
- 65
- 105
4
votes
1 answer
Printing individual moves with the python-chess library
I want to sequentially print the moves (one string per move at a time) from a game I read (using the python-chess library) from a text file.
So, say I have a pgn file with a game that has the following moves...
1. f3 e5 2. g4 Qh4#
... I would like…
BaDer
- 53
- 1
- 3
4
votes
2 answers
Using abstract base class for documentation purposes only
I have a suite of similar classes called 'Executors', which are used in the Strategy pattern. They are very simple classes:
class ExecutorA:
def execute(self, data):
pass
class ExecutorB:
def execute(self, data):
pass
The execute()…
arne
- 4,514
- 1
- 28
- 47
4
votes
1 answer
Is there a way to describe/type-hint the contents of a function's parameters?
I'm trying to learn how to better document my code. Describing a function and just hinting that it receives dict seems to leave any future reader rather short on information though.
Is it common at all to do the following? Or is there maybe another…
NoSplitSherlock
- 605
- 4
- 19
4
votes
1 answer
Swift documentation in Xcode: Multi-line description for function
I'm using Xcode 10 with Swift 5:
There are a couple of big functions in my code that need a detailed, multi-line description. Example:
/**
This is paragraph 1.
This is paragraph 2.
This is paragraph 3.
*/
func Foo() {
//Bla
}
What Xcode…
Neph
- 1,823
- 2
- 31
- 69
4
votes
1 answer
Xcode not formatting document comment properly for Objective-C code
I added the following comment with backtick for code:
/** Checks if the given data is of type `list`. */
+ (BOOL)isList:(id)object {
// ..
}
but the backtick prints as in the Xcode quick help:
How to get Xcode to display code formatted…
John Doe
- 2,225
- 6
- 16
- 44