Thanks for the thorough answers.
On Feb 15, 2010, at 7:32 AM, Tom Trenka wrote:

Oh, one other thing--I'm more than well aware that many of the
examples are not appearing correctly. It's kind of a major issue and
although right now I'm parsing that with a very ugly "guessing game"
hack, I'd like to try to figure out some way of either "correcting"
examples throughout the source code, or have something actually work a
little better WRT to the docparser. What's basically happening is
that examples are being dropped raw into an <example> node (no CDATA,
mind you)
Can't we just change the generator to add a CDATA?
and the markers being used to delineate code samples from
text are being pulled before the block is pushed into the XML. In the
end, the only way I have a clue that something is code rather than
text is by looking for a tab at the beginning of a line, and obviously
that's pretty fragile.
So that does sound like a big issue, but what's worse, it doesn't sound like we have any systematic way to annotate things in the source that are coming out in ways that are *right* but visually incorrect from the docparser. I.e., I'd be great if we had "tags" or annotations in source comments that let us control some of this stuff. I.e., if the dojo.query() output could be augmented with:

// tags:
// function, dom, common

At which point maybe we could generate the cheatsheet-style UI from things that are marked common and grouped by area (e.g., "dom").

How hard would something like this be?
On Mon, Feb 15, 2010 at 9:28 AM, Tom Trenka wrote:
A little background might help.

All of the API documentation (including the Dijit-based tool at
http://api-staging.dojotoolkit.org/ ) is created via the following
process:

1. Run Neil's docparser tools (/util/docscripts/generate.php) with the
XML serialization flag to produce a single XML file;
2. Upload said XML file to a local installation of the dijit-based
tool, where it is run through several XSL transforms (these transforms
are pretty basic, all they do is split out the info in the original
file into 4 smaller ones).

In the case of the docs up on dtk.org now, a third step which spiders
the dijit-based tool and saves each and every "object", as identified
by the generate.php script, is run (in the case of dtk.org, with a
very bare-bones template); we then basically checked it into the
website SVN repo and deployed that way.

I took a look at why query was separate and apparently the docparser
scripts think it is a full-fledged object as opposed to a method on
dojo itself; IIRC the reason for this is because there is a property
added to the dojo.query function--the "pseudos". Because of the
addition of this property, the docparser treats dojo.query almost as
if it were a constructor rather than a straight-up method.

There's a number of other examples throughout the codebase where this
happens; one of the biggest qualifiers seems to be any object that has
another object as a property. You'll see that throughout a lot of
dijit as well. Bear in mind also that the two sets of tools have
their own app domains; the docparser script produces data, and the API
tool consumes it only.

The bottom line (and answer to your first question) is that the
docparser is semantically correct in determining (for the most part)
when something is a pure function attached to an object, and when that
function becomes more than just a function through attaching new
properties to it. I'm not saying that I agree with it entirely from a
doc standpoint though.

The answer to your second question is a bit more...nebulous. No, the
new pages do not let you tag by type; the API tools (the UI ones) are
designed for essentially static output only, and I don't know that the
dream of making it editable wiki-style and having changes pushed back
into the actual source code is a practical one. To get tags by type
there would need to be work done on the parser itself, and though
there were tags added they are actually aimed at marking things as
private, protected, readonly and constant--and they've only been
implemented throughout some of Dijit.

Undoubtedly there's some conditions I'm missing when I'm interpreting
the resultant API XML; for example, I'm not making any real
distinctions between when something's scope is "instance" as opposed
to "prototype" at the moment, and for the most part I'm ignoring most
of the aforementioned tags. I'd also be happy to have someone other
than me look at what I've done (I know Sam Foster has but not sure
about anyone else) to see if there's anywhere we can improve on the
interpretation of the XML files (I'm not super keen on the code
structure at the moment, it was hacked together and is undergoing
somewhat constant improvement). You can take a look at the tool
here:

http://svn.dojotoolkit.org/website/trunk/api/

The relevant interpretation code is sitting in /lib/generate.php (and
before anyone asks, the schema of the XML makes it ridiculously
difficult to get full prototype chains integrated in order via XSLT).
XML data files are in /data/[version]; api.xml is the original upload,
the other four are broken down by purpose. details.xml is probably
the most interesting one to look at.

Hope that helps shed some light--

Tom


On Mon, Feb 15, 2010 at 4:21 AM, Alex Russell wrote:
Howdy all,

First, I love the new API UI. I love that it's integrated into the main site, and I love the clean look of it. Nicely done.

A couple of questions:

* when I look at the main page, some major functions like dojo.query() appear to be entirely MIA, but it does show up under "attached object" and has a separate doc page (http://www.dojotoolkit.org/api/dojo/query.html). What's up with that?
* does the new UI let us tag APIs by "type" so that we can, say, on the main page have categories like we do in the cheatsheet? If not, what's our plan for getting there?

Regards

--
Alex Russell
slightlyoff at google.com
alex at dojotoolkit.org BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723

_______________________________________________
dojo-contributors mailing list
dojo-contributors at mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
_______________________________________________
dojo-contributors mailing list
dojo-contributors at mail.dojotoolkit.org
http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
--
Alex Russell
slightlyoff at google.com
alex at dojotoolkit.org BE03 E88D EABB 2116 CC49 8259 CF78 E242 59C3 9723

Search Discussions

Discussion Posts

Previous

Follow ups

Related Discussions

Discussion Navigation
viewthread | post
posts ‹ prev | 4 of 5 | next ›
Discussion Overview
groupdojo-contributors @
categoriesdojo
postedFeb 15, '10 at 5:21a
activeFeb 15, '10 at 4:06p
posts5
users2
websitedojotoolkit.org

2 users in discussion

Tom Trenka: 3 posts Alex Russell: 2 posts

People

Translate

site design / logo © 2022 Grokbase