Comments (11)
I'm still seeing problems with 0.4.0, do I have to do something to turn this functionality on?
/**
* Description
* @param {Object} p bar
* @param {string} p.foo A bar property.
* @returns {string} desc */
Foo.bar = function(p){};
This is what gets created:
{ title: 'param',
description: 'bar',
type: { type: 'NameExpression', name: 'Object' },
name: 'p' }
{ title: 'param',
description: '.foo A bar property.',
type: { type: 'NameExpression', name: 'string' },
name: 'p' }
from doctrine.
@nzakas It only operates currently on @prop or @Property the docs didn't seem to operate on others.
from doctrine.
It works for @param as well, it's just not documented in the JSDoc 3 site, but it is on the JSDoc Toolkit site: https://code.google.com/p/jsdoc-toolkit/wiki/TagParam
from doctrine.
@nzakas damn, it does however seem slightly better practice to reference objects outside with typedef: http://usejsdoc.org/tags-typedef.html
I suspect this is the better way of defining for JSDoc3.
However I can add this in so at least it can be parsed, we can decide later if the usage should be a warning for JSDoc3 mode perhaps - the article appears to be fairly oldish.
from doctrine.
Maybe @hegemonic can shed some light on this? We use nested properties like this at work all the time.
from doctrine.
@nzakas is correct--JSDoc 3 fully supports the "nested property" syntax for @param
tags. I'll file a ticket to clarify that point in the @param
tag docs.
from doctrine.
@hegemonic thanks for clarifying, I might have to submit some further clarifications to you at some point. Like the inconsistent casings of type's particularly annoy me.
Does using @typedef
for @param
have the same / similar meaning in terms of the generated output?
from doctrine.
@jonathanKingston, sure, feel free to ask questions anytime!
By "inconsistent casings of types," do you mean string
versus String
? JSDoc doesn't care how you capitalize JavaScript's built-in types. Personally, I prefer lowercase for types that are passed by value (string
, number
, boolean
) and title case for types that are passed by reference (Object
, Array.<string>
). That's my own preference, though, not a JSDoc requirement.
In JSDoc 3, the semantics behind @typedef
and nested-property @param
are a little different:
-
@typedef
is meant for complex types (other than classes) that your code uses repeatedly. You document them once, then reuse them in type expressions.In JSDoc's default template, the docs for type definitions are not shown in-line with the list of method parameters. You have to click a link, which takes you to the type definition's docs.
-
@param
with nested properties is useful for one-off objects that are only passed to a single method. For example, you might use this for anoptions
object.
Google Closure Compiler introduces another wrinkle. My understanding is that Closure Compiler encourages liberal use of @typedef
but does not support the nested-property @param
syntax (or, at any rate, does not encourage it).
from doctrine.
At work this is exactly how we use it. Typed efts for reusable things, nested properties for function-specific. Also, we enforce lowercase for primitive types and uppercase for reference types.
from doctrine.
@hegemonic thanks for the clarification.
Yeah I meant just that, most developers seem to use casing to indicate something different.
I know it seems boring but what about each type parameter links to a page about validation? For example all @prop
and @param
linking to a name
article about what is supported and how to validate.
For example its not clear if @namespace
or @this
or @member
support this nested param nature.
Shall I file a ticket on JSDoc to clear this up?
from doctrine.
@jonathanKingston: Off the top of my head, I can't think of any other JSDoc tags that use the nested-property syntax in the way we're discussing it here. It's only relevant for tags that can appear more than once in the same comment block.
Please feel free to file a ticket in jsdoc3/jsdoc3.github.com anytime you'd like something to be clarified in the docs. I'm painfully aware that they have a lot of room for improvement!
from doctrine.
Related Issues (20)
- Support type intersections HOT 9
- What's the reason for the dot in stringifing TypeExpression (Array.<string>)? HOT 3
- Add support for @property without type HOT 2
- Mechanism for 'escaping' @ symbol when part of an example (i.e. Decorators) HOT 5
- Option for allowing multiple tags per line. HOT 1
- Permitting numeric keys in parameter names
- TypeError: Cannot read property 'replace' of undefined HOT 1
- fails to read @name tags with slashes HOT 1
- Using `unwrap` to parse Block comment without `*` separators breaks indentation. HOT 5
- Union type stringification does not respect compact flag
- Support for relative type references HOT 3
- @example warp the decorator does NOT work HOT 3
- The type is in 'name' when there is no name HOT 1
- Record type range gets offset after linebreaks HOT 1
- Support `@access package` HOT 1
- Support for TypeScript import types HOT 1
- doctrine not parsing @Param with default value HOT 1
- Avoid erring with "event:" within `@param` and `@returns` tags and any other allowed contexts HOT 1
- Allow for missing `@param`'s or `@return(s)` with `@implements` on the block; also possibly for @augments/@extends and @override HOT 1
- Archive this repository HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from doctrine.