Early Access: "CoreDoc Explorer" Echo-based JS API Documentation Viewer

tliebeck's picture

A new documentation browser is available for the Echo3's JavaScript API, and it's written in Echo. The "CoreDoc Explorer" tool can also be used to browse your own CoreDoc-generated documentation.

The "CoreDoc" tool itself has been around for some time. It is used to generate API specifications for code written using CoreJS' "Core.extend()" JavaScript inheritance model. The Echo3 JavaScript API Specification has always been generated with this tool. Previous versions were only able to output HTML, but the latest incarnation outputs XML files that are browsable by the Echo-based "CoreDoc Explorer" application.

Click here to see the Echo3 documentation using CoreDoc Explorer. Note that this documentation is for the latest SVN versions of CoreJS, Echo3, Extras, and FileTransfer (exp branch).

Beware that CoreDoc Explorer is in an early alpha stage, it may contain bugs, and there are still some significant features that need to be implemented.

CoreDoc and CoreDoc Explorer are now available in their own SVN repository. (CoreDoc has been removed from CoreJS itself). The new repository location is:

https://svn.nextapp.com/svn/coredoc/trunk

Hi, I get the following

Hi,

I get the following error when entering http://echo.nextapp.com/content/echo3/doc/3.0/cdx/ :

Exception during Client.processUpdates(): Cannot find reference to the Client with which this component should be associated: cannot load peer. This is due to the component's parent's peer not being associated with a Client. Component = CL.2/ContentPane

tliebeck's picture

What browser/OS are you

What browser/OS are you using?

FF 3.0.12, WinXP

FF 3.0.12, WinXP

Awsome!

Great work! Wouldn't it be cool to have something like this for javadocs and more complete sample apps?

tliebeck's picture

Thanks! It should be

Thanks!

It should be possible to adapt this project to browse JavaDocs, but it'd take some effort. The "CoreDoc Explorer" app simply reads XML files. Here are the XML files it's looking at:

http://echo.nextapp.com/content/echo3/doc/3.0/cdx/content/

It first reads the Index.xml file: http://echo.nextapp.com/content/echo3/doc/3.0/cdx/content/Index.xml to get the list of classes/namespaces, and then loads additional "Class.???.xml" files as necessary.

JavaDoc would need to be extended to generate documentation in a similar format (think it's designed to be able to, but have never really poked around with it). And the CoreDoc Explorer app would need to be modified a bit as well.

Another app is almost completed...the "chat" thing I've mentioned in the past..and it's a good bit bigger than this one.

XML Spec

Do you have an XML spec of some sort? DTD or maybe just a complete list of tags with where and how they should be used? Then I can definitely look into the javadoc see if it can generate something in the same format.

---
Just found this: http://jeldoclet.sourceforge.net I believe all we need is a "translation" code either stand alone or embedded into your code, preferably the latter since we can take the jeldoclet output straight up. Then again, we can always pipeline the process to make it more modular like apache cocoon.

tliebeck's picture

Don't have an XML spec/DTD.

Don't have an XML spec/DTD. At present a tremendous amount of thought has not been put into the XML format...that's not to say that it's horrid, but it was not a huge concern given that one product is both the producer and consumer of the XML data. This also means that there won't be any hard feelings if it needs to change. If there's any (de-facto) standard out there for XML API documentation, or some rather popular format, I'd be up for adopting it.

oliverp's picture

Fails

Hi,
unfortunately it also fails for me using the URL: http://echo.nextapp.com/content/echo3/doc/3.0/cdx/
This seems to be the same issue like adeon. Red screen appears (see Attachment).

Environment:
- Ubuntu 9.04
- Firefox 3.0.12

tliebeck's picture

Not certain what's going on

Not certain what's going on here, but am looking into it. I'm running the exact same environment (9.04+3.0.12). Have also tried 3.5.

tliebeck's picture

Can anyone who is having the

Can anyone who is having the crash issue see it in a different browser, or is the behavior the same in all browsers? And I assume the demo app still works fine?

tliebeck's picture

Additionally, what FF

Additionally, what FF plugins are you all running? And are you 32-bit or 64-bit?

tliebeck's picture

ONE MORE THING :D

Could you both try it one more time and post the error message again? I've put an updated version up which produces a more detailed exception.

oliverp's picture

Error Details Ubuntu 9.04

Hi,
no problem - I like to help and I'am willing to try it 100 times if necessary.

Environment:
Dell D820
Ubuntu 9.04 64 Bit, 2.6.28-13, x86_64
Firefox 3.0.12 (Plugins: Firebug)

I still get the error on my environment:
This application has been stopped due to an error.
Exception during Client.processUpdates(): Cannot find reference to the Client with which this component should be associated: cannot load peer. This is due to the component's parent's peer not being associated with a Client. Component = CL.2/ContentPane, Parent = CL.1/Root, Parent Peer = [object Object], Parent Peer Client = [object Object]

Solution
Disable Firebug.

PS: Tod, how can you live without Firebug? Do you use any other tools, or do you have some other doubts?

tliebeck's picture

Yikes...statement is:

Yikes...statement is:

        if (!component.parent || !component.parent.peer || !component.parent.peer.client) {
            throw new Error("Cannot find reference to the Client with which this component should be associated: " +
                    "cannot load peer.  This is due to the component's parent's peer not being associated with a Client. " +
                    "Component = " + component + ", Parent = " + component.parent + ", Parent Peer = " + 
                    (component.parent ? component.parent.peer : "N/A") + ", Parent Peer Client = " + 
                    ((component.parent && component.parent.peer) ? component.parent.peer.client : "N/A"));
        }

All expressions in that if statement should have evaluated to false...so FireBug (or something else) is really screwing things up here.

Are you sure it only happens when Firebug is enabled? I'm not able to replicate it even with Firebug...wonder if the problem requires a 64-bit machine as well (totally guessing here, could be something else).

I tend to be on the slow side when it comes to adding new tools. I think I tried Firebug a long time ago and it had some issues somewhere, can barely recall though. I just installed the latest, and it looks slick enough to keep around for a bit, provided I can get an understanding of why it's causing this problem.

Huge thanks for finding the cause!

I use Firebug on FF 3.5.1 on

I use Firebug on FF 3.5.1 on Leopard. Doesn't seem to the problem. I believe it's 64 bit in Leopard(?)

oliverp's picture

Bug in Firebug 1.4.0 (upgrade to Firebug 1.4.1)

Hi,
I just got the same issue in my echo3 application and its for sure Firebug 1.4.0. But today i updated to version 1.4.1 and everything is fine. So i think there is a bug in firebug 1.4.0 causing this error.

Regards,
Oliver

PS: The CAPTCHA is nice, its training the brain... cool.

Same for me, no error with

Same for me, no error with firebug 1.4.1

tliebeck's picture

Thanks both, good to hear it

Thanks both, good to hear it was just a Firebug issue.

And yeah, the math CAPTCHA's were fun, but alas, they proved too difficult for me. Hence the new image based items. :D