Opened 8 years ago

Closed 7 years ago

Last modified 7 years ago

#14019 closed defect (fixed)

The 1.7 docscripts does not generate the doc for properties.

Reported by: tissandier Owned by: dante
Priority: high Milestone: 1.8
Component: Documentation Version: 1.7.0b1
Keywords: Cc: cjolif
Blocked By: Blocking:

Description

The sample is a 'doctest' module containing one class, 'doctest.A', with one method and two properties. If you try to generate the doc for this module, the XML output contains the correct info for the class and the method, but nothing is generated for the properties.

(Note that the two properties are defined slightly differently, one is an instance property defined inside the class, the other one is a "static" property defined globally on the A class object, with doc-only code added so that it is correctly documented. This is just because in our use case we use these two types of properties, but the problem seems to be the same in both cases: all properties are just missing).

To reproduce:

  • unzip the archive at the same level as dojo/dojox/dijit
  • move doctest.module.properties to util/docscripts/modules
  • open a command prompt window, go to util/docscripts and execute:

php generate.php doctest

  • look at the result in cache/api.xml

The output does not contain any info for the properties (instanceProperty/staticProperty).

Doing the same using Dojo 1.6 works fine, the output contains the correct doc info for both properties.

Note that the sample uses the legacy (non-AMD) syntax just to be able to verify that it works in previous versions, but we have the same problem in pure AMD modules.

Attachments (1)

doctest.zip (560 bytes) - added by tissandier 8 years ago.

Download all attachments as: .zip

Change History (20)

Changed 8 years ago by tissandier

Attachment: doctest.zip added

comment:1 Changed 8 years ago by tissandier

Priority: normalhigh
severity: normalcritical

comment:2 Changed 8 years ago by dante

Owner: set to dante

comment:3 Changed 8 years ago by cjolif

Cc: cjolif added

I think the bug hurts dojo 1.7 doc as well. See for example dijit.CalendarLite? it does not contain any documented property while the source code shows some.

comment:4 Changed 8 years ago by Tom Trenka

It's possible that the template string definitions in CalendarLite?, which come before the documented properties, are a good part of the problem. I'd suggest first moving those to the bottom of the property definitions and see if you run across the same issue.

comment:5 Changed 8 years ago by cjolif

Tom, thanks for the suggestion but I took CalendarLite just as an example. If you look at dojo.Animation you will also see missing properties (like repeat, rate..)... Same thing for dojox.charting.Chart. So it seems to be a rather general issue? Or am I missing something?

comment:6 Changed 8 years ago by Adam Peller

What has to happen here? Should this hold up rc2 or is this independent of the sources?

comment:7 Changed 8 years ago by cjolif

I'm far from a doc API tool expert but my feeling is the issue is in the doc tool not in the javascript source code (because similar source code passed to 1.6 doc tools works fine). I don't know it holds a RC but it would hold a release I would say? Because the doc is clearly incorrect?

Version 0, edited 8 years ago by cjolif (next)

comment:8 Changed 8 years ago by Tom Trenka

I would say it should hold up a release but not an RC. In general though (and I went and played a little with CalendarLite?, but not too much) if some files produce full docs and others don't, it's usually because of the way the docs are written in the code itself (at least from previous experience). Anything that shows in the preview tool should generate in the full-on parser.

comment:9 Changed 8 years ago by tissandier

Not so sure ttrenka. You can look at the provided sample. I could not find an error in the way the documentation is written and it does reproduce the error. I am afraid the problem is in the tool.

comment:10 Changed 8 years ago by Tom Trenka

If I get a chance to look at it later (probably during the meeting), I will see. But it shouldn't hold up an RC (that was my main point).

Hopefully dante/phiggins can take a looksee before then; I don't really know the parser code all that well.

comment:11 Changed 8 years ago by tissandier

I agree it should not prevent from building the rc

comment:12 Changed 8 years ago by dante

verified from test case. preview.php is showing the members as collected, so the issue is in the generation/serialization step. We'll probably hit this a lot as I start fine-tooth-combing the API conversion, but I'm not seeing anything obvious jumping out wrt to changes I made for AMD-unwrapping in the parsing aspect ... The 'dumpobj' script also finds the members, but fails to be found when serializing:

{"#debug":[],"#raw_source":"dojo.provide(\"doctest.A\");\n\ndojo.declare(\"doctest.A\", null, {\n\t\/\/ summary:\n\t\/\/\t\tA dummy class to test the API doc generation tool.\n\n\/*=====\n\t\/\/ staticProperty: int\n\t\/\/\t\tA static property defined on the doctest.A object.\n\tstaticProperty: 999,\n=====*\/\n\n\t\/\/ instanceProperty: int\n\t\/\/\t\tAn instance property whose value is 99.\n\tinstanceProperty: 99,\n    \t\t\n\tsomeFunction: function(someArg){\n\t\t\/\/ summary:\n\t\t\/\/\t\tA test function.\n\t\t\/\/ someArg: string\n\t\t\/\/\t\tThe argument of the function.\n\t} \n\t\n});\n\ndoctest.A.staticProperty = 999;\n","#provides":"doctest.A","#resource":"A.js","doctest.A":{"type":"Function","summary":"A dummy class to test the API doc generation tool.","classlike":true},"doctest.A.staticProperty":{"prototype":"doctest.A","type":"int","summary":"A static property defined on the doctest.A object.","attached":"doctest.A"},"doctest.A.instanceProperty":{"prototype":"doctest.A","type":"int","summary":"An instance property whose value is 99."},"doctest.A.someFunction":{"prototype":"doctest.A","parameters":{"someArg":{"name":"someArg","type":"string","summary":"The argument of the function."}},"summary":"A test function.","type":"Function"},"doctest":{"type":"Object"}}

comment:13 Changed 8 years ago by Adam Peller

Milestone: 1.71.7.1

comment:14 Changed 8 years ago by Kenneth G. Franqueiro

Priority: highnormal
severity: criticalnormal

comment:15 Changed 8 years ago by Colin Snover

Milestone: 1.7.11.7.2

Bumping unclosed 1.7.1 tickets to next minor version.

comment:16 Changed 7 years ago by Colin Snover

Milestone: 1.7.21.7.3

1.7.2 RC released, bumping milestone on remaining tickets.

comment:17 Changed 7 years ago by cjolif

We are apparently still hitting that one :-(

comment:18 Changed 7 years ago by Colin Snover

Resolution: fixed
Status: newclosed

Fixed in new doc parser.

comment:19 Changed 7 years ago by Colin Snover

Milestone: 1.7.31.8
Note: See TracTickets for help on using tickets.