oxymoron / ext-doc Goto Github PK

If user specifies in his/her project xml file extra tags he/she wants to
get in docs like:

<tags>
   <tag name="author" value="Author"/>
   <tag name="version" value="Class Version"/>
<tags>

Ext.emptyFn found as method, but it's a property (1.0.96)

It seems to be a bug in ExtJS Docs... 

 /**
     * @cfg {Boolean} <p>enableDragDrop True to enable dragging of the
selected rows of the GridPanel.</p>
     * <p>Setting this to <b><tt>true</tt></b> causes this GridPanel's
{@link #getView GridView} to create an instance of 


But in ExtJS Help it is fine... 

but description is wrong:

                 True to enable dragging of the selected rows of the
GridPanel.</p>

Per ExtJS Message Board:
  - http://extjs.com/forum/showthread.php?p=348358#post348358

PROBLEM: 
When passing a method an object as a parameter, you cannot document the
required attributes of that object. (This can be done in JSDoc Toolkit, as
I mention in the above forum post).

What steps will reproduce the problem?
1. Open any class that has parents in IE

What is the expected output? What do you see instead?

No indentations comparing to FF

What steps will reproduce the problem?
1. Create file structure for source multiple levels deep (may not be necessary)
2. Create source file with name similar to the following: NS.Type.File.js
3. Compile documentation using extdoc

What is the expected output? What do you see instead?
Expected:
"Defined In" and "Class" references that point to the source file should go
to something similar to: /NS.Type.File.html#cls-NS.Type.Classname
Actual:
"Defined In" and "Class" references point to source files similar to:
/NS.html#cls-NS.Type.Classname

Desired effect:
Have compiler gracefully accept source files with multiple periods, instead
of expecting source files to follow the "name.js" naming convention.

What version of the product are you using? On what operating system?
ext-doc-1.0.131
Windows 7

Please provide any additional information below.
I will see if I can find anything in the source to fix this myself, but I
figured other people must be affected by it. Our naming convention involves
putting the entire namespace in the filename, followed by the
super-category. I.E. Namespace of Process.grid with a display class would
result in the file "Process.grid.Display.js" and within that file you will
find classes such as "Process.grid.Display.MultiColumnGrid" etc.... The
compiler is breaking on the naming convention for the javascript files, and
leading to invalid source file pointers (and the source files are not even
generated).

There should be more class-level tags (like @singleton) which will display 
a special icon in the documentation tree. For example, in the online ExtJS 
documentation you can see various icons in the tree (namely, the 
"component" icon). 

This would be helpful as some classes aren't created directly, but are 
extended or used in some way by other classes. The icon would be a visual 
cue to developers and help to further organize the output documentation.

Ideally, each tag would insert some basic text in the class's header 
(exactly as the @singleton tag), though discussion would be needed for each 
particular tag.

Some examples might be:
  - @base
  - @component

In ext.js we have

/**
 * @class Function
 * These functions are available on every Function object (any JavaScript 
function).
 */
Ext.apply(Function.prototype, {...});

And I have a file adding some utilities to Function.prototype too:

/**
 * @class Function
 * extra utilities to Function
 */
Ext.apply(Function.prototype,{..});

In this case Ext-doc generates two differents results with the same name. 
We have Function class twice. This was reported here 
(http://www.extjs.com/forum/showthread.php?p=292346#post292346) before.

What steps will reproduce the problem?
1. Add an inline comment to a block of code with a <pre> html tag
2. Generate

What is the expected output? What do you see instead?
Comments wrapped in <i>[comment]</i> is expected; there's an extra newline 
before the last </i>, which in a <pre> block causes problems.


What version of the product are you using? On what operating system?
1.0.3.1 on Win7


Please provide any additional information below.

example of problem with linked file:
http://ext-doc.org/docs/source/GridP...toExpandColumn

go to:
http://ext-doc.org/docs/?class=Ext.grid.GridView

    * dragZone
    * getHeaderCell


http://ext-doc.org/docs/?class=Ext.Container

    * add


Appears to be inconsistent success handling html tags in the properties.
__________________
http://extjs.com/forum/showthread.php?p=288796#post288796

link to the actual JS from "defined In"

http://alexgorbatchev.com/wiki/SyntaxHighlighter

only realtive path works fine

Run ext-doc against the latest ExtJS release. Debugging statements added to 
tree.xsl show the document its fed contains the duplicates. Run {{{sort 
output/tree.js | uniq -c | sort}}} to see offending entries.

What steps will reproduce the problem?
1. Just run the sample

What is the expected output? 
Author: oxymoron
Version: 1.0.101
Demo: test
brick-icon: brick-icon

What do you see instead?
Nothing

What version of the product are you using? On what operating system?
Ubuntu 8.04

Please provide any additional information below.

What steps will reproduce the problem?
1. Create a comment with <pre><code>    something</code></pre>
2. Generate

What is the expected output? What do you see instead?
Expected: the whitespace should remain
Actual: the whitespace is removed


What version of the product are you using? On what operating system?


Please provide any additional information below.

What steps will reproduce the problem?
1. Click several pages from the nav tree on the left
2. Click the browser back button and you will go back to previous HTML page, 
but not the previous tab you opened

What is the expected output? What do you see instead?
It would be great if it could go back to the previous tab you opened in the 
doc viewer (like http://extjs.edspencer.net/extjs/docs/)

What version of the product are you using? On what operating system?
Snapshot from Monday 22/03/2010

[deleted issue]

Optionally, generate placeholder documentation for methods, fields and events 
that have no docblock (thus forcing the developer to either write the 
documentation or at least provide a dummy docblock with an @ignore tag). 
Currently, there is no way to find missing documentation.

Develop new "Plain" Template

This is fixed locally, submitting here to integrate with main version.

What steps will reproduce the problem?
1. Host the documentation under arbitrary path on server, like
http://extjs-ux.org/ext-docs
2. Examine the "Direct link" href in the right-top corner

What is the expected output? What do you see instead?
It will be like
"http://extjs-ux.org/docs/index.html?class=Ext.ux.event.Broadcast"

Should be 
It will be like
"http://extjs-ux.org/ext-docs/index.html?class=Ext.ux.event.Broadcast"

What version of the product are you using? On what operating system?
ext-doc-1.0.131 plus some modifications from ExtJS team for 3.0

Attaching fix.

Would it be a lot of work to create an index file with the keywords for
every class/config option/property/method/event during the doc build?

Such a file could be used to fill a server table for online search or even
to create an offline search feature (will require postprocessing to split
and format the data, so javascript can handle the amount of information).

What steps will reproduce the problem?
1. Copy the attached source file into the samples folder:
samples/ext/sources. Remove everything else from there.
2. Run sample script "ext-doc.sh".
3.

What is the expected output? What do you see instead?
The steps above reproduce a NullPointerException in class
"extdoc.jsdoc.processor.FileProcessor". Here is the stacktrace: 

Processing: Repository.js
Exception in thread "main" java.lang.NullPointerException
        at
extdoc.jsdoc.processor.FileProcessor.processEvent(FileProcessor.java:476)
        at
extdoc.jsdoc.processor.FileProcessor.processComment(FileProcessor.java:535)
        at
extdoc.jsdoc.processor.FileProcessor.processFile(FileProcessor.java:618)
        at
extdoc.jsdoc.processor.FileProcessor.processDir(FileProcessor.java:772)
        at
extdoc.jsdoc.processor.FileProcessor.processDir(FileProcessor.java:768)
        at extdoc.jsdoc.processor.FileProcessor.process(FileProcessor.java:811)
        at extdoc.Main.main(Main.java:80)


What version of the product are you using? On what operating system?

I'm using the latest snapshot from 2009-10-19:
http://ext-doc.org/upload/ext-doc-1.0-SNAPSHOT.zip

Please provide any additional information below.

Reset current class when new file is processing

If I move @author or @version before the class description, the UI fails. It 
thinks that the description is part of author or version, depending on which 
one I test.

Test:

/**
 * @class SamplePackage.SampleClass
 * @extends Ext.Panel
 * @author oxymoron
 * This is a sample class <br/>
 * {@link SamplePackage.SampleClass#methodOne this is method one} <br/>
 * {@link SamplePackage.SampleClass#methodOne} <br/>
 * {@link #methodOne another link} <br/>
 * {@link #methodOne} <br/>
 * {@link SamplePackage.SampleClass} <br/>
 * {@link SamplePackage.SampleClass sample class} <br/>
 * @version 1.0.101
 * @demo test 
 */

Presently documentation that includes <pre> text has to omit asterisks,
which results in somewhat ugly comments.  This can easily be changed to
permit comments like this:

/**
 * Text description blah blah...
 *
 * <pre><code>
 * function makeFour () {
 *   return 2 + 2;
 * }
 * </code></pre>
 */

Which looks nicer.

The following diff implements this change, while not altering the
processing of old style comments without leading asterisks.

This operates by removing all the whitespace up to the asterisk, the
asterisk, and a single space following the asterisk, if present.

===================================================================
--- java/src/main/extdoc/jsdoc/tags/impl/Comment.java   (revision 173)
+++ java/src/main/extdoc/jsdoc/tags/impl/Comment.java   (working copy)
@@ -52,7 +52,7 @@
         return false;
     }

-    private enum CommentState {SPACE, DESCRIPTION}
+    private enum CommentState {SPACE, DESCRIPTION, ONESPACE}

     private enum InnerState {TAG_NAME, TAG_GAP, IN_TEXT}

@@ -80,6 +80,8 @@
                                 if (isStarWhite(ch)){
                                     if (ch == '*'){
                                         foundStar = true;
+                                        state = CommentState.ONESPACE;
+                                        break;
                                     }
                                     spaceBuffer.append(ch);
                                     break;
@@ -90,6 +92,10 @@
                                 spaceBuffer.setLength(0);
                                 state = CommentState.DESCRIPTION;
                                 /* fall through */
+                            case ONESPACE:
+                                state = CommentState.DESCRIPTION;
+                                if (ch == ' ')
+                                    break;
                             case DESCRIPTION:
                                 if (ch == '\n'){
                                     foundStar = false;

What steps will reproduce the problem?
    /**
     * @cfg
     */
    autoEl : {
        tag : 'img',
        cls : 'tng-managed-image',
        src : Ext.BLANK_IMAGE_URL       
    },

What is the expected output? What do you see instead?
=========================
Exception in thread "main" java.lang.StringIndexOutOfBoundsException:
String index out of range: 0
        at java.lang.String.charAt(String.java:687)
        at extdoc.jsdoc.tags.impl.TagImpl.removeBrackets(TagImpl.java:56)
        at extdoc.jsdoc.tags.impl.CfgTagImpl.<init>(CfgTagImpl.java:23)
        at
extdoc.jsdoc.tags.impl.Comment$1CommentStringParser.parseCommentComponent(Commen
t.java:175)
        at
extdoc.jsdoc.tags.impl.Comment$1CommentStringParser.parseCommentStateMachine(Com
ment.java:155)
=========================

What version of the product are you using? On what operating system?
Both snapshot and ext-doc-1.0.131 have this problem

Please provide any additional information below.

Navigation tree highlighting works wrong if packages has same name ex:
Ext.form Ext.ux.form

What steps will reproduce the problem?
1. put js files into ext\source folder
2. run the ext-doc.bat

What is the expected output? What do you see instead?
>java -jar ../ext-doc.jar -p ext.xml -o ../output -t ../
template/ext/template.xml -verbose
Processing: XYZ.js
Java error stack trace 
*** COPY RESOURCES ***
*** COPY SOURCE FILES ***
Target folder: ../output\source
ERROR:  'unknown protocol: c'
FATAL ERROR:  'Could not compile stylesheet'
javax.xml.transform.TransformerConfigurationException: Could not compile 
stylesheet
        at 
com.sun.org.apache.xalan.internal.xsltc.trax.TransformerFactoryImpl.newTemp
lates(Unknown Source)
        at 
extdoc.jsdoc.processor.FileProcessor.saveToFolder(FileProcessor.java:1000)
        at extdoc.Main.main(Main.java:83)



What version of the product are you using? On what operating system?
windows xp sp3

Please provide any additional information below.

Patch to add some additional functionality.

First integrated JSAP-2.1 CLI parser. It's licensed LGPL
(http://www.martiansoftware.com/jsap/license.html). Try doing running java
-jar ext-doc.jar -h

Also added the ability to recursively process a directory(s) (*.js files)
instead of using a XML file list.

Usage:
  * just apply the patch
  * copy JSAP-2.1.jar to the lib/ dir.
  * rebuild and GO!

e-mail me with any questions.

ex: GridPanel @hide is visible

What steps will reproduce the problem?
1. Go on API-Home
2. Search for SampleClass
3. View results

What is the expected output? What do you see instead?
Expected result is a link to the SampleClass available in the documentation. 
Actual result is no 
results found

I recon the Ajax call is done directly to extjs.com website.

No JS Code Highlighting

Inline tags should be short: "Record" instead of "Ext.data.Record.Record"
(see Store class)

What steps will reproduce the problem?
1. Create file structure for source multiple levels deep (may not be necessary)
2. Create source file with name similar to the following: NS.Type.File.js
3. Compile documentation using extdoc

What is the expected output? What do you see instead?
Expected:
"Defined In" and "Class" references that point to the source file should go
to something similar to: /NS.Type.File.html#cls-NS.Type.Classname
Actual:
"Defined In" and "Class" references point to source files similar to:
/NS.html#cls-NS.Type.Classname

Desired effect:
Have compiler gracefully accept source files with multiple periods, instead
of expecting source files to follow the "name.js" naming convention.

What version of the product are you using? On what operating system?
ext-doc-1.0.131
Windows 7

Please provide any additional information below.
I will see if I can find anything in the source to fix this myself, but I
figured other people must be affected by it. Our naming convention involves
putting the entire namespace in the filename, followed by the
super-category. I.E. Namespace of Process.grid with a display class would
result in the file "Process.grid.Display.js" and within that file you will
find classes such as "Process.grid.Display.MultiColumnGrid" etc.... The
compiler is breaking on the naming convention for the javascript files, and
leading to invalid source file pointers (and the source files are not even
generated).

Sorting order is like AaBbCc, but original Ext Docs has ABCabc

"Key constant" expected

Static methods could not be inherited ex.: Ext.Panel  method Observable.capture

I'd like to have a configuration parameter that lets you build a completely
offline documentation (without the search feature).

With offline documentation, I mean that it can be opened directly from the
file system, without the need of a web server.

Right now, with the ajax requests, the browsers don't let you open directly
the files.

Link tags in the form of {@link #someLocalAttrib} that appear in class
docBlocks dont work. 

This is caused because the description of the docBlock is processed in
processClass() before context.addDocClass(cls) is called which means when
processLink() is called with a link similar to above the current class is
Null or Invlaid when processLink() tries to call
context.getCurrentClass().className.

Also MEMBER_REFERENCE_TPL is missing a class reference.

Examples of this can be found in the class docBlocks of:
Ext.Updater
Ext.Component

Attached is a small patch to move processing of descriptions after the
current class is registered with the context. It also fixes the
MEMBER_REFERENCE_TPL.

What steps will reproduce the problem?
1. Create an ux, starting from high-level namespace, which is different
from Ext, like: 'JooseX.Bridge.Ext'
2. Generate docs.

What is the expected output? What do you see instead?
Expected (note Joose, JooseX namespaces):
http://extjs-ux.org/docs/
Seen (none of those):
http://extjs-ux.org/ext-docs/

What version of the product are you using? On what operating system?
Probably some patched version on Ubuntu 8.04

add .sh file for mac and linux users

What steps will reproduce the problem?
1.
2.
3.

What is the expected output? What do you see instead?


Please use labels and text to provide additional information.

What steps will reproduce the problem?
1. Add the @constructor tag
2. Have no @method tags in your class
3. The constructor never appears in the output docs

What is the expected output? What do you see instead?
  I expect to see the constructor listed in the "Public Methods" section

What version of the product are you using? On what operating system?
  v1.0.131 on Windows Vista


Doing this works:
/**
 * @class My.Class
 * Description of My.Class
 * @namespace My
 * @extends Ext.util.Observable
 * @constructor
 * @param {string} myString Description of myString
 */
My.Class = function(myString){
    /**
     * @method
     */
    this.myMethod = function() {};
};


Doing this does not work (no @method defined):
/**
 * @class My.Class
 * Description of My.Class
 * @namespace My
 * @extends Ext.util.Observable
 * @constructor
 * @param {string} myString Description of myString
 */
My.Class = function(myString){
    this.myMethod = function() {};
};

To have multiple extends in a class is very usefull for get all members,
including parent class members, in doc of child class.

@author tag. This would make it easy to keep track of who created what.

Disable _classname.html generation in output for releases

adobe air version

Ext.EventManager public properties are missing

The current matching attribute allows simple wildcard matching. 

Using regular expressions would give the user more control over the including 
and excluding of specific filenames. The code already converts the simple 
wildcard into a regular expression, so the change should be minimal.