Stack Overflow
Stack Overflow

Questions tagged [code-documentation]

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.

381 questions
244
votes
3 answers

JSDoc: Return object structure

How can I tell JSDoc about the structure of an object that is returned. I have found the @return {{field1: type, field2: type, ...}} description syntax and tried it: /** * Returns a coordinate from a given mouse or touch event * @param …
BlackWolf
  • 5,239
  • 5
  • 33
  • 60
214
votes
5 answers

codestyle; put javadoc before or after annotation?

I know that it isn't the most vital of issues, but I just realised that I can put the javadoc comment block before or after the annotation. What would we want to adopt as a coding standard? /** * This is a javadoc comment before the annotation …
Paul McKenzie
  • 19,646
  • 25
  • 76
  • 120
154
votes
5 answers

How to document a string type in jsdoc with limited possible values

I am having a function that accepts one string parameter. This parameter can have only one of a few defined possible values. What is the best way to document the same? Should shapeType be defined as enum or TypeDef or something…
Shamasis Bhattacharya
  • 3,392
  • 3
  • 20
  • 24
88
votes
7 answers

Is there a consensus on what should be documented in the class and __init__ docstrings?

I did not find any best practice about what should be documented in the class and __init__ docstrings. Sometimes I find that the constructor arguments are already documented in the class docstring, sometimes the are described in the __init__…
causa prima
  • 1,502
  • 1
  • 14
  • 24
80
votes
5 answers

Adding line breaks to c# comments for Intellisense

Does anyone know how to insert a line break into a summary comment in order for the line break to be reflected in Intellisense documentation? To clarify, assume code documentation.. /// /// Some text documentation /// - a line break -…
flesh
  • 23,725
  • 24
  • 80
  • 97
68
votes
1 answer

Is it possible to merge two pages created by SandCastle into a single main page?

For each class in the project, SandCastle creates (among others) two pages: The main page, called as T_class_full_name, with the description, Syntax, Inheritance Hierarchy and See Also The members page, called as AllMembers_T_class_full_name, with…
Martin Haluza
  • 1,075
  • 7
  • 17
64
votes
6 answers

Documenting Node.js projects

I'm currently using JSDoc Toolkit to document my code, but it doesn't quite fit - namely, it seem to struggle with describing namespaces properly. Say you have two simple classes in each their files: lib/database/foo.js: /** @class */ function…
Morten Siebuhr
  • 6,068
  • 4
  • 31
  • 43
59
votes
6 answers

What do the three arrow (">>>") signs mean?

I haven't been able to figure out what the >>> does, even though I often see it often in source code.
Dumle29
  • 809
  • 1
  • 6
  • 13
49
votes
4 answers

How do I generate API documentation for SignalR

Is there a way to do this? I have swashbuckle generating content for my other APIs but I don't believe it works for SignalR.
LivingOnACloud
  • 1,151
  • 1
  • 11
  • 20
43
votes
1 answer

opencv python documentation

Recently, I want to use the OpenCV library in Python, but the documentation of Python binding of OpenCV is very unclear and insufficient. I want to ask where to find some detailed documentation of Python binding of OpenCV. Previously I used OpenCV…
Jun Wang
  • 607
  • 1
  • 6
  • 14
39
votes
8 answers

What Are Best Practices For Documenting C# code with XML comments?

I'm going through some new code I just wrote and adding NDoc sytle comments to my classes and methods. I'm hoping to generate a pretty good MSDN style document for reference. In general, what are some good guidelines when writing comments for a…
Esteban Araya
  • 29,284
  • 24
  • 107
  • 141
36
votes
2 answers

Swift 3 error: "See also" callout not showing

I just migrated my project to Swift 3 and found that the "See also" callout in the quick help is not showing. Everything was perfectly working in the previous version of Swift. Below is my code: /** Adds a "See also" callout in the Quick Help for a…
Tapas Pal
  • 7,073
  • 8
  • 39
  • 86
35
votes
7 answers

Create "Quick Help" Entry in Xcode

How do I create quick help entries in Xcode for my own code? I just want it as a coding support, meaning like the Eclipse functionality when coding Java. In eclipse you get a comment you entered above a method when hovering a method somewhere…
m Jae
  • 725
  • 2
  • 8
  • 20
30
votes
4 answers

How to write documentation comments in ANSI C?

I can't find how to write comments in C. I mean I know about // and /* */, what I mean is where can I find good practices? Like if I have a function, how do I write the @param variable is the value bla bla, like it is done in Java? Are there any…
bb2
  • 2,872
  • 7
  • 37
  • 45
29
votes
5 answers

PHPdoc - defining object properties for an object of stdClass

I am trying to figure out if it is possible to use PHPdoc to define the object properties being returned by a function or a object method. Say I have the following class: class SomeClass { public function staffDetails($id){ $object =…
someuser
  • 2,279
  • 4
  • 28
  • 39
1
2 3
…
25 26