[ng-dhtml] Fwd: [Dojo-checkins] alex - r1867 - trunk/documents/manual/rest

Dylan Schiemann mail at dylans.org
Fri Oct 21 00:42:57 CDT 2005


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Bill,

Basically through several IRC chats, it was decided against because it
is very difficult to parse correctly without adding a bunch of extra
attributes/information, and we wanted to avoid the docbook style
comments used in nWidgets (they completely overwelmed the codebase
itself).  It has worked really well for MochiKit, which gave us
confidence that such an approach would be useful.

Not that there aren't valid arguments for the other approaches (most
importantly duplication of effort), but this is what the community
decided we thought we wanted to do given our lack of great options.

- -Dylan

Bill Keese wrote:
> I thought "documentation" meant something like "Javadoc", written into
> the .js files and then extracted programatically.  I guess the plan is
> something different?
> 
> Alex Russell wrote:
> 
>>We now have a documentation template, so for everyone who has 
>>volunteered to help write docs, now's the time!
>>
>>Regards
>>
>>  
>>
>>
>> ------------------------------------------------------------------------
>>
>> Subject:
>> [Dojo-checkins] alex - r1867 - trunk/documents/manual/rest
>> From:
>> dojo-checkins at dojotoolkit.org
>> Date:
>> Thu, 20 Oct 2005 21:29:31 -0700 (PDT)
>> To:
>> dojo-checkins at dojotoolkit.org
>>
>> To:
>> dojo-checkins at dojotoolkit.org
>>
>>
>>Author: alex
>>Date: Thu Oct 20 21:29:30 2005
>>New Revision: 1867
>>
>>Added:
>>   trunk/documents/manual/rest/template.rest
>>Log:
>>adding a reST template for documentation. Fixes #136
>>
>>
>>Added: trunk/documents/manual/rest/template.rest
>>==============================================================================
>>--- (empty file)
>>+++ trunk/documents/manual/rest/template.rest	Thu Oct 20 21:29:30 2005
>>@@ -0,0 +1,109 @@
>>+.. title:: dojo.namespace.* -- The Dojo Manual
>>+
>>+.. this is a comment. for more information on reST, see:
>>+   http://docutils.sf.net/docs/user/rst/quickstart.html
>>+   http://docutils.sf.net/docs/user/rst/quickref.html
>>+
>>+Name
>>+===============================================================================
>>+
>>+dojo.namespace.* - do that thing that namespaces do
>>+
>>+Summary and Overview
>>+===============================================================================
>>+
>>+Please enumerate the major functions of your namespace here in sufficient
>>+detail to allow a reader to understand why they might want to require it and
>>+what down-sides doing so might have.
>>+
>>+Usage
>>+===============================================================================
>>+
>>+::
>>+
>>+    var ret = dojo.namespace.doSomething("arg1", "arg2");
>>+    dojo.namespace.exerciseYourFunctions(ret);
>>+    dojo.debug("huzzah!");
>>+
>>+
>>+API Reference
>>+===============================================================================
>>+
>>+Classes
>>+---------------------------------------
>>+
>>+``Foo(arg1)``:
>>+
>>+    Please eneumerate constructor argument types here and describe the classes
>>+    function.
>>+
>>+    *Inherits from*:
>>+        nothing
>>+
>>+    ``arg1``:
>>+        a very arg-like argument
>>+
>>+    *returns*:
>>+        new object of type Foo.
>>+
>>+``Foo.prototype.method1()``:
>>+
>>+Properties
>>+---------------------------------------
>>+
>>+``foo``:
>>+
>>+    A string that has many foo-like propeties. Defaults to "thud".
>>+
>>+``bar``:
>>+
>>+    Object reference to an instance of ``dojo.namespace.Bar``
>>+
>>+Methods
>>+---------------------------------------
>>+
>>+``baz(arg1)``:
>>+
>>+    describe ``dojo.namespace.baz()`` here.
>>+
>>+    ``arg1``:
>>+        An argument. Like many others, but different in its own special way.
>>+
>>+    *returns*:
>>+        null
>>+	
>>+
>>+Requires
>>+===============================================================================
>>+
>>+- `dojo.hostenv`_
>>+- `dojo.other.namespace`_
>>+
>>+.. _`dojo.hostenv`: 		hostenv.html
>>+.. _`dojo.other.namespace`:	other.namespace.html
>>+
>>+Provides
>>+===============================================================================
>>+
>>+dojo.namespace.Foo
>>+    A class constructor that allows Foos to be created
>>+
>>+dojo.namespace.Bar
>>+    A class constructor that allows Bars to be created, although you might need
>>+    a liquor license in your own municipality to actually operate the created
>>+    Bars.
>>+
>>+To Do
>>+===============================================================================
>>+
>>+Lots. But that's always true.
>>+
>>+About
>>+===============================================================================
>>+
>>+:Author: Alex Russell
>>+:Version: 0.1
>>+:Copyright: Dojo Foundation, 200x
>>+:Date: YYYY/MM/DD
>>+
>>+.. vim:ts=4:et:tw=80:shiftwidth=4:
>>_______________________________________________
>>Dojo-checkins mailing list
>>Dojo-checkins at dojotoolkit.org
>>http://dojotoolkit.org/mailman/listinfo/dojo-checkins
>>  
>>
>>------------------------------------------------------------------------
>>
>>_______________________________________________
>>NG-DHTML mailing list
>>NG-DHTML at netwindows.org
>>http://mail.netwindows.org/mailman/listinfo/ng-dhtml_netwindows.org
>>  
>>
> 
> 
> ------------------------------------------------------------------------
> 
> _______________________________________________
> NG-DHTML mailing list
> NG-DHTML at netwindows.org
> http://mail.netwindows.org/mailman/listinfo/ng-dhtml_netwindows.org
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (Darwin)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFDWH/g8nLgh/JJsxERAhezAKCYt8Qth0RVUYrS5hCAB7oHAxe/agCbBK4o
nsWRFtCbAjEH0Fo1/O5Grxc=
=l9gc
-----END PGP SIGNATURE-----



More information about the NG-DHTML mailing list