Apidoc readme: clarify exportable methods #2140
Conversation
| @@ -22,7 +22,7 @@ contain Markdown. | |||
|
|
|||
| The second line tells the Closure compiler the type of the argument. | |||
|
|
|||
| The third line (`@todo api`) marks the method as exportable. The stability can be added as value, e.g. `@todo api stable`. Once the documentation story is fully settled, we will remove the `todo ` and just write `@api` or `@api stable`. Without such an api note, the method will not be exported and not documented in the generated API documentation. | |||
| The third line (`@todo api`) marks the method as part of the api and thus exportable. The stability can be added as value, e.g. `@todo api stable`. Once the documentation story is fully settled, we will remove the `todo ` and just write `@api` or `@api stable`. Without such an api note, the method will not be documented in the generated API documentation; those not directly exported with `goog.exportProperty` will also not be exportable. | |||
There was a problem hiding this comment.
those not directly exported with
goog.exportPropertywill also not be exportable
It is not clear to me what you are trying to say here.
The truth is that where we have goog.exportProperty calls in the source, properties are unconditionally exported (independent of any @todo api annotation). The presence of a @todo api annotation in this case means that these exported properties will also be documented (this is a good thing).
There was a problem hiding this comment.
are there cases where there is a goog.exportProperty but no @todo api? I was assuming not.
There was a problem hiding this comment.
My point is that the two things are independent. goog.exportPropery unconditionally exports a symbol. The @todo api annotation makes a symbol "exportable" (with the build tools) and generates documentation.
Your comment that methods "not directly exported with goog.exportProperty will also not be exportable" is unclear to me. Can you explain what you are trying to say?
There was a problem hiding this comment.
I'm trying to clarify what's currently in there. At the moment "Without such an api note, the method will not be exported" isn't correct. Those that have goog.exportProperty will be exported whether there's an api note or not (though I would assume that these 'always exported' methods should also have an api note).
There was a problem hiding this comment.
How about this instead:
Without such an api annotation, the method will not be documented in the generated API documentation. Symbols without an api annotation will also not be exportable (unless they are explicitly exported with a goog.exportProperty call).
|
sorry, need to rebase - revised version coming up |
|
ok, your suggestion incorporated |
Apidoc readme: clarify exportable methods.
Re-add reference to the 'always exported' methods for completeness, otherwise it's not entirely correct