Dear Dev, As we've all known for a long time now, the OpenLayers project has been in dire need of some serious documentation. We have tried hand creating it in text files, in wikis, using jsdoc, even writing our own version of jsdoc (cr5!).
And then, as if by divine intervention, a post came in to the dev list last week from Glen S. about a tool called "Natural Docs". Our esteemed contributor Tim S. took to it immediately, creating his own sandbox[1] where he began playing around with the tool and adding the new NaturalDocs (ND) style comments. Chris Schmidt and I have looked over the great work that Tim has done and we are both convinced that ND is the best solution we've seen yet for getting a clean set of dynamically created docs up and running for the OpenLayers project. Other members of the steering committee have also been vocal about their approval. The move to running automatic ND doc creation and therefore shifting our coding style accordingly will likely go to an official vote in the PSC sometime later this week. Before we do so, we want to run this by the community one more time. Please, if you have a spare moment, take a look at the wiki[2] that Tim has created which very clearly explains the changes we'll need to make to run ND on the project. Check out the live ND docs[3] which are being generated from Tim's sandbox. If there's something you don't like, or maybe something you think we haven't thought of, please send a post to this list -- we want your input! If you like what you see and want to help us out with the conversion, send me an email and you can join us with the translation of the different sections. If all goes well, we could have this great new system up and running by the end of this week or early next. Again, big thanks going out to Glen for recommending this tool and especially to Tim S who has benevolently and almost single-handedly taken it from an idea into a reality. Let us know what you think! --Erik [1] http://dev.openlayers.org/sandbox/tschaub/naturaldocs/ [2] http://trac.openlayers.org/wiki/NaturalDocs [3] http://dev.openlayers.org/naturaldocs _______________________________________________ Dev mailing list [email protected] http://openlayers.org/mailman/listinfo/dev
