Files/Directories parsing order change

Currently, there is no enforcement on the order files and folders are
parsed into a directory. In my installation (Windows), folders are always
being parsed first. It would be better to enforce it, having files parsed
first and folders later.

== Rational ==

In the CKEditor project we use a file naming convention that is quite
common. File names match class names. You can see it here:

http://dev.fckeditor.net/browser/CKEditor/trunk/_source/core

For example, the events.js file represents the CKEDITOR.events class. We do
that for core objects also, like CKEDITOR.env.

Note that we also have folders there. For example the "dom" folder. That's
because we have a namespacing convention being considered here. So, the
CKEDITOR.dom.element class is defined inside "dom/range.js".

We also have the dom.js file, which describes and documents the
CKEDITOR.dom namespace.

The problem is that "dom/range.js" is being parsed first, and so we have
the "Trying to document CKEDITOR.dom.range without first documenting
CKEDITOR.dom" warning.

Making sure that files are parsed first and folder later would fix the
warning and would not bring any drawback to current installations that
don't care about the parsing order.

Original issue reported on code.google.com by fre...@gmail.com on 8 Jan 2010 at 11:33

I can't reproduce this, here's what I tried: I made a simple example with two 
files: dom.js and dom/range.js.

These contain:

/**  In dom.js
    @name dom
    @namespace
 */

/**  In dom/range.js
    @name dom#range
    @function
 */

And indeed the files are processed in this order: range.js then dom.js. But 
there is no warning message and the docs are as 
expected.

In fact I even put the two comments into a single file, in the wrong order, 
like so:

/**
    @name dom#range
    @function
 */
/**
    @name dom
    @namespace
 */

And, again, this does not produce any warning or problem.

Are you certain that the problem you are experiencing is caused by the order in 
which the files are processed? Can you create 
a very simple example that demonstrates the problem, and include that with this 
bug report?

Original comment by micmath on 10 Jan 2010 at 5:47

Changed state: MoreInfoRequired

swallowzhang / jsdoc-toolkit

Files/Directories parsing order change #277