Titanium JIRA Archive
Titanium SDK/CLI (TIMOB)

[TIMOB-10240] APIDoc: Add "notes" or "see" field to "deprecated" annotation

GitHub Issuen/a
TypeNew Feature
PriorityMedium
StatusClosed
ResolutionFixed
Resolution Date2012-08-24T10:53:14.000+0000
Affected Version/sRelease 3.0.0
Fix Version/sSprint 2012-17 Core, Release 3.0.0
ComponentsTooling
Labelsn/a
ReporterArthur Evans
AssigneeBill Dawson
Created2011-12-09T13:16:35.000+0000
Updated2012-11-26T21:46:57.000+0000

Description

It would be nice if the deprecation annotation included a free-text field where we could describe what to use instead. The alternative is to reuse the summary text, possibly removing the only documentation describing the item. This proposal is to add a field, which for the sake of argument I'll call notes, like this: 
deprecated:
    since: 1.8.0
    removed: 1.9.0
    notes: Use <Titanium.UI.iPhone.Hicky> instead.
For summary tables, the deprecated.notes field could be used in place of the summary, so users would see something like: bq. DEPRECATED Use instead. For the detail page, the note would show up as part of the deprecation warning, and the usual summary would appear: bq. Deprecated since 1.8.0, removed in 1.9.0. Use instead. bq. bq. Summary bq. A view which automatically renders as an octagon.

Comments

  1. Bill Dawson 2012-08-17

    I'll start this by updating validate.py, the spec, and the htmlgenerator (though we don't really use that, it's nice to have.) For the jsduck changes probably we should have a separate ticket, since it'll start getting "weird" if we have multiple people making PRs for the same ticket.
  2. Bill Dawson 2012-08-21

    Testing Notes

    * Open apidoc/Titanium/Network/TCPSocket.yml in an editor. * In the type's deprecated block, add: 
           notes: Use <Titanium.Network.Socket.TCP> instead.
    * Save the file. * Run python apidoc/validate.py -e -s simple for a sanity check. (It has been updated for this.) * Run python apidoc/docgen.py. * When it's finished, open dist/apidoc/index.html in a web browser. * Navigate to the Titanium.Network.TCPSocket documentation page. * Make sure the deprecation information includes the "Use Titanium.Network.Socket.TCP instead" comment, and that "Titanium.Network.Socket.TCP" is a link that, when clicked, properly goes to the Titanium.Network.Socket.TCP documentation page.
  3. Bill Dawson 2012-08-21

    Pull request ready: https://github.com/appcelerator/titanium_mobile/pull/2803
  4. Natalie Huynh 2012-11-26

    Tested with 3.0.0.v20121121161553, do not need to add notes, it is already added so just run validation

JSON Source