Titanium JIRA Archive
Titanium SDK/CLI (TIMOB)

[TIMOB-7419] Tooling: docgen.py Add support for inheriting individual fields from parent

GitHub Issuen/a
TypeNew Feature
PriorityHigh
StatusClosed
ResolutionFixed
Resolution Date2012-06-15T09:42:14.000+0000
Affected Version/sRelease 2.0.1
Fix Version/sRelease 2.1.0, Sprint 2012-12 Core
ComponentsTooling
Labelscore
ReporterArthur Evans
AssigneeBill Dawson
Created2012-01-26T09:03:27.000+0000
Updated2012-06-15T16:19:44.000+0000

Description

This is a feature request that came up during documentation work. When overriding a method in an inherited object, we currently need to recreate the entire method description in order to update a single field. It would be helpful to be able to inherit these descriptions. Something like: - name: someMethod summary: @inherit description: | Makes the view rotate 360 degrees then turn purple. parameters: @inherit returns: true Or alternately: - name: someMethod inherit-docs: true description: | Makes the view rotate 360 degrees then turn purple. This would be a time-saver and prevent some copy & paste errors, but it doesn't give us anything we can't do today, so not a top priority.

Comments

  1. Paul Dowsett 2012-05-18

    We need this for events and properties too.
  2. Bill Dawson 2012-05-22

    Do you guys think we even need special syntax? I was thinking maybe we can make it such that you only specify the fields you want to change, and no need to put any other type of special syntax indicating that you want inheritence. Validate would then need to be changed to not ding you if you don't put a required field, of course.
  3. Arthur Evans 2012-05-24

    So, I'm not sure we need a special syntax. Not having the special syntax would make a little more work up front, but less work later. Let me explain: We currently have a bunch of places where we've repeated methods, properties, etc., that are actually inherited, in order to modify the platform tags, etc. We can't know for sure whether adding the partial inheritance is going to modify the doc for any of these members. So ideally, we'd want a flag like --warn-inherited that prints a warning message when "filling in" an inherited field for an API member. So if Hickey has method: 
       name: flense
   summary: Flenses the hickey and returns a Blob of blubber.
   returns: 
       type: Titanium.Blob
    And DooHickey redeclares it thus: 
       name: flense 
   summary: Flenses the doohickey and throws away the blubber.
    We'd get a message something like this: 
       DoHickey.flense -- inheriting return type from Hickey.flense
    Is that practical? Thanks, -Arthur
  4. Bill Dawson 2012-05-29

    Agreed, I like the flag idea.
  5. Bill Dawson 2012-06-14

    Testing Notes

    * Open apidoc/Titanium/Media/VideoPlayer.yml * Find the "click" event documentation. * Delete everything from the click event documentation except "description", and make the description be "Click event test for VideoPlayer." So the complete click event documentation will look like: 
       - name: click
     description: Click event test for VideoPlayer
    * Run python apidoc/docgen.py --warn-inherited. As its generated, you should see warnings for documentation properties that are being inherited from the documentation of super types. * When docgen is finished, open dist/apidoc/index.html in the browser, and navigate to the titanium.Media.VideoPlayer documentation. Make sure the documentation for the click event looks right (has its summary, etc.) and shows a description as you entered it above. * Run python apidoc/validate.py -- you should get no errors related to the VideoPlayer.
  6. Bill Dawson 2012-06-14

    PR ready: https://github.com/appcelerator/titanium_mobile/pull/2393

JSON Source