my own documentation approach

First i want to say, that the grid is a fantastic piece of javascript code.
I programmed grids, like this one, now for years, but never achieved this level of quality.
Alex, I know what pain you must suffering, trying to make it work crossbrowser ( safari or opera ).

I dropped all my code and use now your grid.

There are a few things i did not understand or could not make it work, so i 'extends' the grid with my own event-handler.

My first suggestion is, instead of expanding the grid with more and more needed features: create a minimal version.
Lets say to split it into different autonomous modules. Each part work on its own and can be replaced by another code.
In fact you did it in the code, but lack of documentation everybody(at least me) loose the overview and ends up doing it hardcoded, even when there are the needed function.

I thought of following separate parts
grid renderer important is a dynamic startpoint within the myData Array , like the patch, deliver hash tables of pointer to rows and cols, like table.rows[].cells[]
event handler addEvent, removeEvent
grid shaper setColStyle, setRowStyle, resizeCol, ...
grid manipulator addRow, remowRow, addColumn, removeColumn, expandRow, expandCol, moveColumn ...
data grabber getFromXML, getFromSOAP, getFromCVS
action logger records all modifications on a grid and submits it each onchange or other event.

but after all, i spent a few day looking at your code and came to the conclusion, that a good documentation will do much more than i wish.

What i can do is write a simple php script like the phpDocumentor but for javascript.
For that reason somebody !!! (not me) has to reformat all the comments in the code to one defined standard. i suggest to use the phpDocumentor style:

/**
* blablaintro
*
* much more blabla
*/
var or function code

but any other will do, as long as it is always equal and before the code.

here a rough sketch for the php code:
grab all js files from the lib

serach and replace all "{" width "<div class='expander' onclick='toogle(this.nextSibling)'>{</div>"
serach and replace all "}" width "</div>"
search and replace all "/**\n" width "<div class='comment'>";
search and replace all "*/\n" width "</div><div style='float:right;'>[commentImage]</div>";
etc.
maybe js search functionality...

i made a small example with the existing grid source:

http://webmail.mbn.ch/table/doc.php

adding extra markers allows to comment text by everybody like in a bb.

nb: the wiki part is a good start

Andres Obrero [Winterthur]

March 15,

just i case someone is interested how i did it.
As an extension of the idea, it would be nice to click on a function call and then jump to the function definition. But the grid code is much more object oriented (this is a compliment) as normally, so it is not easy to guess the corresponding function, unless there is a bit more information in the sourcecode.

Here the PHP

<head>
<style>
body{ font-family:verdana;}
.file{ display:none;}
h2{	margin:0px, padding:0px; font-size:12pt;
    cursor:hand; cursor:pointer;
}
.bracket{
    cursor:hand; cursor:pointer;
    color:red;
    font-weight:bold;
    background-color:yellow;
    padding-left:10px; padding-right:10px;
}
.cc{
    position:absolute;
    cursor:hand; cursor:pointer;
    color:red;
    font-weight:bold;
    background-color:yellow;
}
.comment{
    color:green;
    display:none;
    position:absolute;
    background-color:#DDDDDD;
    border:solid 1px #999999;
}
.inside{
    display:none;
    border:solid 1px red;
    margin:2px;
    margin-left:10px;
    padding:4px;
}
</style>
<script>
//----------------------------------
function _absLeft(obj) { return (obj.offsetParent)? obj.offsetLeft+_absLeft(obj.offsetParent) : obj.offsetLeft; }
function _absTop(obj) { return (obj.offsetParent)? obj.offsetTop+_absTop(obj.offsetParent) : obj.offsetTop; }
function toggle(obj){ obj.style.display = (obj.style.display == "block") ? obj.style.display = "none" : obj.style.display = "block"; }

//----------------------------------
function showC(e,obj){
    var nn = obj.nextSibling;
    nn.style.top = _absTop(obj) +"px";
    nn.style.left = (_absLeft(obj) + obj.offsetWidth +5 )+"px";
    nn.style.display = "block";
}
//----------------------------------
function hideC(e,obj){
    var nn = obj.nextSibling;
    nn.style.display = "none";
}
//----------------------------------
</script>
</head>
<body>
click on <span class='bracket'>{</span> Symbol and mouseover <span class='cc'>[...]</span>
    to open a file: click on the name.
<?php
$start = dirname(__FILE__)."/dyntable/";

getAlljs($start);

/******************************************
 * find files recursively all folders and print 
 */
function getAlljs($dir){
    $files = findMatchFiles($dir, "/.js/i");
    if(is_array($files))
        foreach($files as $file){
            echo "<h2 onclick='toggle(this.nextSibling)'>$file</h2><div class='file'>";
            parseFile($dir,$file);
            echo "</div><!-- end file $file -->\n\n";
        }
    $dirs = findDirs($dir);
    if(is_array($dirs))
    foreach($dirs as $odir){
        getAlljs($dir.$odir."/");
    }
}
/******************************************
 * find files
 */
function parseFile($dir, $file){
    $data = file_get_contents($dir.$file);
    $data = str_replace(array("\n\n", "{", "}", "/*", "*/"),
    array(
        "\n",
        "<span class='bracket' onclick='toggle(this.nextSibling)'>{</span><span class='inside'>",
        "</span>}",
        "<span class='cc' onmouseover='showC(event, this)' onmouseout='hideC(event, this)'>[...]</span><div class='comment'>/*",
        "*/</div>"), $data);

    echo "<pre>\n$data</pre>";
}
/******************************************
 * find files
 */
function findMatchFiles($dir,$regexp){
        @$dir = dir($dir);
        if($dir){
            if ($regexp != null) {
                while ($file = $dir->read()) {
                    if (preg_match($regexp, $file)) {
                        $result_array[] = $file;
                }
            }
        }
        $dir->close();
        return $result_array;
    }else
        return array();
}

/******************************************
 * find directories
 */
function findDirs($odir){
    @$dir = dir($odir);
    if($dir){
        while ($file = $dir->read()) {
            if ($file != "." && $file != "..") {
                if (is_dir($odir.$file)) {
                    $result_array[] = $file;
                }
            }
        }
        $dir->close();
        return $result_array;
    }else
        return array();
}
?>
</body>

Andres Obrero [Winterthur]

March 15,

Actually I have a script that automatically extracts comments from the source code. The reference pages were produced using this (custom) script.

http://www.activewidgets.com/documentation/reference/active.controls.grid/index.htm

I don't think any off-the-shelf tool will do this because there is so much functionality generated on the fly by defineXXX() calls. Even myself I could not solve it with the source code only - I used a combination of the source parsing and introspection of running copy of the code. Actually nearly all source code (except a few global functions) is available during runtime because it is inside 'create class' methods.

From your post I understand that it would make sense to combine the reference documentation with the actual source code using comments folding and hyperlinking for function names. I think its a good idea and I'll try to implement that. Also would be cool to allow editing the comments in wiki-way and feed them back into the source :-)

Alex (ActiveWidgets)

March 15,

I also started writing the programming guide (in very small steps :-)

http://www.activewidgets.com/general.doc/
http://www.activewidgets.com/general.doc/overview.html

Alex (ActiveWidgets)

March 15,

Can you make the steps bigger please?

June 9,

This topic is archived.

my own documentation approach

See also:

Search

New Data Grid

Version 2