code-documentation

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 {TouchEvent|MouseEvent|jQuery.Event} e * A valid mouse or touch event or a jQuery event wrapping such an * event. * @param {string} [type="page"] * A string representing the type of location that should be * returned. Can be either "page", "client" or "screen". * @return {{x: Number, y: Number}} * The location of the event */ var getEventLocation = function(e,

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 */ @Component public class MyClass { @Autowired /** * This is a javadoc comment after the annotation */ private MyOtherClass other; } Peter Jaric Before the annotation, since the annotation is code that "belongs" to the class. See examples with javadoc in the official documentation. Here's random example I found in another official Java page : /** *

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 else? Shape.prototype.create = function (shapeType) { // shapeType can be "rect", "circle" or "ellipse"... this.type = shapeType; }; Shape.prototype.getType = function (shapeType) { // shapeType can be "rect", "circle" or "ellipse"... return this.type; }; The second part of the problem is that the possible values of shapeType is not known in the file that defines