Comments (12)
What is the use case for @Private, @Protected, and @public?
I think the use case is for overriding the TypeScript visibility for external libraries which seems to match the @internal
use case.
// file-1.ts
class Foo {
/**
* I want this to be easily accessible in my code but not used by library users
* @protected
*/
public bar
}
It sounds like the recommendation should be to avoid tags like these (including @readonly
) that override the native TypeScript semantics.
Standardizing the release tags (or "API Contract" tags?) makes sense. The Angular team uses @experimental
and @stable
tags. If you look at their API docs they also handle @depricated
and a special @security
tag
from tsdoc.
Looks like they removed @stable
Here's their list of tags
https://github.com/angular/angular/tree/master/aio/tools/transforms/angular-api-package/tag-defs
Here is where the stable property is calculated
https://github.com/angular/angular/blob/658f49f650dd90c784312845e63061d3268f5c84/aio/tools/transforms/angular-api-package/processors/computeStability.js#L7-L14
from tsdoc.
@pgonzal - sorry I'm a bit late to this party. @aciccarello is spot on. We use dgeni to do our documentation generation, which by itself does very little.
The bulk of the processing is in dgeni-packages which includes a jsdoc package and also typescript package. The former parses out jsdoc tags (which are completely configurable on a project by project basis) and the latter parses TS source code and infers lots of properties that would otherwise need jsdoc tags.
On top of that we have project specific configuration in the angular project at https://github.com/angular/angular/tree/master/aio/tools/transforms.
The list of tags linked to above is the "standard" ones that that the jsdoc package supports but for our purposes we add in a bunch of extra ones via https://github.com/angular/angular/tree/master/aio/tools/transforms/angular-api-package/tag-defs and https://github.com/angular/angular/tree/master/aio/tools/transforms/content-package/tag-defs. Some of which might be out of date and unused 😱.
As @aciccarello points out, this is not the whole story because we can then modify docs before they are rendered by processors, which is what is happening in the computeStability
processor for the stability flags.
Happy to provide more detail of all of this if it is helpful to anyone.
from tsdoc.
Thanks very much for digging this up!
from tsdoc.
Thanks very much for providing this detail! I am almost done converting API Extractor to use the TSDoc library prototype, and then my next step will be to audit the various other documentation tools that people have provided links to, and start an initial draft of a standards doc proposing detailed syntaxes for all the tags.
There's a preliminary sketch in StandardTags.ts.
from tsdoc.
@readonly
AEDoc's @readonly
tag was introduced for a weird edge case like this:
export class Widget {
private _name: string;
get name(): string {
return this._name;
}
/** @readonly */
set name(value: string) {
throw new Error('The "name" property is read-only');
}
}
// JavaScript caller:
var w = new Widget();
w.name = 'oops';
Normally API Extractor documents a property as read-only based on the lack of a setter. However, in this case the setter is performing validation. The API was created with TypeScript, but it can also be consumed by pure-JavaScript scripts that aren't aware of the type system.
I believe this can probably be deprecated now. IIRC the evolution was like this:
- Originally
w.name = 'oops'
(without setter) would silently overwrite the property getter with a string field, which was terrible - After some tech upgrades, instead the assignment would do nothing, which was less damaging, but still highly confusing
- Today with
"use strict"
, I believe it throws an exception
So as long as all the modern stuff has the semantics from # 3, we probably can retire this particular tag.
Other tags already captured by the TypeScript language
What is the use case for @private
, @protected
, and @public
? If it's just holdovers from JSDoc's non-TypeScript world, then perhaps TSDoc tools should strip these tags, and try to avoid introducing new semantics for them.
Tags that extend the TypeScript semantics
For API Extractor's scenarios which go beyond the TypeScript language (e.g. @internal
, @alpha
, @beta
, @public
), it might be useful to coordinate with other tools that want these concepts, to ensure that the tags have consistent semantics everywhere. I'm pretty open to changing the naming/semantics.
We have received a bunch of feature requests that already would require some improvements to our naming/semantics. Example requests:
-
I want to mark something as "internal" but only within my project. This way my unit tests can access it, but other libraries that access "internals" cannot.
-
When I expose my library internals, I want to control which libraries have access to it. Something like C#'s "InternalsVisibleTo" or C++'s "friend".
-
When I mark something as "internal" for other first-party projects to consume, I want a way to designate it as "internal-beta" until the API contract is stable.
These needs mainly arise in large ecosystems with hundreds of projects and many teams who are trying to formalize their code-sharing relationships and responsibility for breakages.
from tsdoc.
Having default visibility for external libraries inferred from TypeScript modifiers (private, public, protected) seems way better than explicitly writing tags for every item.
But at the same time, if you need to override the visibility explicitly, it would be nice if you could do that.
What is a bit unclear to me is how do be disambiguate a situation like this:
When I expose my library internals, I want to control which libraries have access to it. Something like C#'s "InternalsVisibleTo" or C++'s "friend".
It seems that documentation of visibility might become very cluttered/verbose if someone has 2-3 parties with different visibilities of API.
On the other hand, if you really need to have different visibilities for different parties, you'd be happier having ability to specify that rather than having to maintain multiple d.ts'es or solve this in some hacky way.
So, if we're thinking of specifying party-specific API contract tags, we're better doing that from the start.
from tsdoc.
Because visibility is not runtime enforceable, I think these modifiers would be purely suggestive. The user would determine whether they should be accessing @internal
or @beta
apis just as someone would choose whether they are okay with using a @depricated
api.
from tsdoc.
All of the tags here are standalone tags, i.e. whose presence acts as a simple on/off switch. They could probably be moved anywhere within the doc comment without ambiguity.
The one exception is @deprecated
. For AEDoc, we require that @deprecated
is required by a nonempty message that indicates what should be used instead. For example:
/**
* The base class for all widgets.
* @deprecated The BaseWidget class has been superseded by the BaseControl class.
* @public
*/
class BaseWidget {
...
}
This would generate a documentation banner like this:
! | This API is now obsolete. The BaseWidget class has been superseded by the BaseControl class. |
from tsdoc.
@aciccarello wrote:
Standardizing the release tags (or "API Contract" tags?) makes sense. The Angular team uses
@experimental
and@stable
tags. If you look at their API docs they also handle@depricated
and a special@security
tag
Do you happen to know the name (or GitHub project) for Angular's API documentation tool? I am trying to cite it as an example. I found this api-builder folder, but it seems obsolete.
from tsdoc.
I think the config is now somewhere in angular/angular/aio/tools. They have some build setup based on angular/dgeni.
@petebacondarwin could probably explain things better.
from tsdoc.
Also if there's a listing somewhere of their supported tags, that would be useful. I'm having trouble finding example usages of the @stable
tag.
from tsdoc.
Related Issues (20)
- Upgrade Node.js and `node-sass` dependencies HOT 1
- Validate invalid params through tsdoc eslint plugin HOT 1
- This repo is missing important files
- Documentation coverage? HOT 1
- JSDoc/TSDoc `@inherit[dD]oc` mismatch HOT 1
- Is it dead? HOT 4
- VS Code unable to load Schema
- tsdoc-unnecessary-backslash false positive
- Weird warnings about multiple declarations HOT 1
- Grouping classes under the same index name
- Support for defining custom tag syntax HOT 1
- tsdoc-html-tag-missing-equals erroneously flagging boolean attributes
- tsdoc-malformed-html-name erroneously flagging use of less than symbol HOT 1
- Unable to load schema from 'https://json.schemastore.org/tsconfig HOT 1
- `tsdoc-reference-unquoted-identifier` is incorrectly reported for certain identifiers
- [ Question ][ Playground ] Intended Behaviour? HOT 2
- eslint-plugin-tsdoc: Missing rule to check for absence of a TSDoc comment HOT 1
- ESLint flat configurations? HOT 1
- "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json"
- Can inherit doc also copy the TSDoc when I hover?
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 tsdoc.