dean.edwards.name/weblog/2007/08/base2-doc/

Documentation for base2

I’ve finally produced some documentation for base2. It is still incomplete but at least it’s a start. The base2 core is mostly documented now. The core is tiny (6KB gzipped) but includes enough juicy bits to allow me to build something more complex like base2.DOM.

Neither base2 nor base2.DOM are officially released yet but you can use the beta versions hosted here:

The two files above are also merged into a single file:

http://base2.googlecode.com/svn/version/1.0(beta2)/base2-dom-fp.js

Note: -p(acked) version, -f(ull) version.

The documentation is written using MiniWeb. I did this for two reasons. First, I wanted an excuse to use MiniWeb for something. Second, I wanted to separate my documentation from my source code, I dislike paging through reams of comments when I’m debugging. The MiniWeb documentation system builds skeletal documentation based on the code it finds in the page. It includes an editor and a navigation system so that I can start browsing my APIs, documenting as I go.

At the moment the documentation system is only suitable for base2 code. It would be a relatively simple matter to support other styles of JavaScript. A previous incarnation did just this. Is there any interest in a more generic documentation system or are people happy with NaturalDocs et al. ?

Comments (24)

Leave a comment

A previous incarnation did just this. Is there any interest in a more generic documentation system or are people happy with NaturalDocs et al. ?

There is interest, most definitely. Neither NaturalDocs nor JSDoc is nimble enough for modern JavaScript coding styles.

Indeed, there is interest. Just from browsing around the base2 docs I’m convinced that this documentation style is very useful and fluid.

It would be great if there were a simple way to plug in different JS styles/grammars so the documentation method could be used for different libraries and such.

Thanks for this, particulary the examples, it’s very helful.

Thanks for your great work!

Hmm, well it’s a fine thing but every new request turns my browser for 1-2minute into a ‘frozen’ state. That’s kinda … long.

FF newest version. Processor: AMD Athlon 1GHz. 586MB SD-RAM. Yes, my PC is a little older, but such an app should also run on my machine.

@gossi – really? I’ll have to check it out on my old box. Do you have Firebug enabled?

Yeps

When I first load the page. Firebug says 56.84s to load all the javascript files. But the total size to load is about 20KB at all ?!?. Well, Fasterfox measured a loading time of ~165 seconds. During this time, RAM-Usage of FF grows from 60MB to 71MB. CPU-Usage is at 95% – 99% at FF and FF is frozen as mentioned above…

Hope that helps.

Great to see that – now we can see what’s really in those 40k

Hmm, loading this page now, takes 114.434secons (Fasterfox). Weird, it’s the only page, that loads thaaat long…

@gossi – I tried on my oldest machine (500Mhz/256 MB RAM) and it performs fine. The application does not do a lot of processing so I wonder what your problem is. The reason I asked about Firebug is that sometimes this can slow down applications. Have you tried disabling it?

Wow,

I disabled Firebug now and it’s really fast, cool. Don’t know Firebug is my FF slowdown *g*.

@gossi & dean

I tried even an older system and it performs without any problems. So the application can’t be the reason for the long page load.

@gossi I also tried it my very old machine (800Mhz/256 MB RAM) and it works fine. I use Firebug and it don’t slow down my PC. I think You have to check Your PC for other thing like viruses etc.

The documentation style is great! It’s a tad bit messy in the CSS, but other than that the idea is great!

@Darius – yeah I’m not the world’s greatest designer. If anyone wants to fix the CSS then go for it:

http://base2.googlecode.com/svn/trunk/src/apps/doc/base2.html#/system/view!/doc/system/view.css

Thanks for the documentation, should be a big help! Really easy to find what you are looking for.

@gossi – I just ran into the problem of glacial loading too. The problem is that you have firebug installed and the user preference javascript.options.strict set to true. That combo is logging a pretty impressive amount of warnings to the error console.

http://groups.google.com/group/base2-js/browse_thread/thread/c39ebc2ea178864b

Set javascript.options.strict to false (via about:config) and all will be well again.

Comment: #18

[…] http://dean.edwards.name/weblog/2007/08/base2-doc/ […]

Comment: #19

[…] I’ve had some complaints recently that my site was taking an age to load in Firefox. In fact, anything built with base2 was performing very badly for some Firefox users. My advice to them was to disable Firebug. This solved the problem but I didn’t know why. I use Firebug and wasn’t experiencing any slow down. […]

Hey dean just wanted to say thanks for all of the hard work that you have been putting into this project, as well as the others you have developed. Keep it up and I look forward to seeing what you come out with next.

Indeed, there is seductiveness . Just from browsing around a base2 docs I’m assured which this support character is really utilitarian as well as fluid.

It would be good if there were a elementary approach to block in opposite JS styles/grammars so a support process could be used for opposite libraries as well as such.

Thanks for the documentation Dean, it is really a good idea to separate documentation from code, because it is simpler this way to read and understand.

indeed, there is seductiveness . Just from browsing around a base2 docs I’m assured which this support character is really utilitarian as well as fluid.

Hello , The documentation style is great! It’s a tad bit messy in the CSS, but other than that the idea is great!

Comments are closed.