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

Search Discussions

  • Tom Trenka at Feb 15, 2010 at 10:28 am
    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
  • Tom Trenka at Feb 15, 2010 at 10:32 am
    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) 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.

    -- Tom
    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
  • Alex Russell at Feb 15, 2010 at 3:34 pm
    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
  • Tom Trenka at Feb 15, 2010 at 4:06 pm
    No problem--I've been trying =)
    On Mon, Feb 15, 2010 at 2:34 PM, Alex Russell wrote:
    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?
    It looked to be a bit more involved than that, like something really
    custom to the XML serialization needs to be written and handled. For
    the most part Neil's generator generates things in a PHP format (basic
    object serialization) and then attempts to translate it, and (being
    the markdown n00b I am) I'm not sure if the original intention was to
    try to run everything through markdown first or not.
    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?
    Short answer: I don't know, though I think "tags" was co-opted for the
    aforementioned private, protected, readonly etc. thing. Might have to
    come up with some other identifier.

    Keep in mind also that part of the serialization process was an
    attempt at matching (not entirely but closely) some of the OpenAjax
    specifications for docs, and they never seemed to consider (as far as
    I know) the idea of tags in the webbish sense. Hopefully (doubtfully
    but hopefully) I'll get more time to look closer at it this coming
    weekend, kind of fried at the moment =(

    -- Tom
    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

    _______________________________________________
    dojo-contributors mailing list
    dojo-contributors at mail.dojotoolkit.org
    http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors

Related Discussions

Discussion Navigation
viewthread | post
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