[Dojo-checkins] [dojo] #2675: Multiple updates for doc parser

[dojo]

#2675: Multiple updates for doc parser
---------------------------------------------+------------------------------
 Reporter:  toby.collett at onetrackmind.co.nz  |        Owner:  pottedmeat
     Type:  enhancement                      |       Status:  closed    
 Priority:  normal                           |    Milestone:  future    
Component:  Doc parser                       |      Version:  0.4.2     
 Severity:  normal                           |   Resolution:  wontfix   
 Keywords:                                   |  
---------------------------------------------+------------------------------
Changes (by pottedmeat):

  * status:  new => closed
  * resolution:  => wontfix


Old description:

> The attached patch is made up of the following parts:
>
> 1) fixes to the tree walker to allow the parser to run on non dojo trees
> (also simplifies it)
>
> 2) Adds 'tags' as a special comment field
>
> 3) Allows filtering of what is included in the output files based on the
> tags, private members and can strip source.
>
> 4) Allows configuration of which paths, namespace prefixes and filters
> are run from the command line
>
> Tags work as follows
> {{{
> Idea:
>         Add tags to doc parser. These could be useful for segmenting
> generated
>         documentation for different audiences. (eg. internal team vs
> clients,
>         contribs vs users)
>
>         When the docparser runs it would produce a set of tags for each
>         object/function/var/...
>
>         1. They could be used to filter the parser output before it was
> used in
>         the ApiRef so there is no overhead of downloading stuff that is
>         never/should never be displayed.
>
>         2. They could be used in the display of documentation in any
> form, or as
>         it is converted to another form (XSD).
>
>         In source, tags are specified whereever you can have a summary.
> Comma or
>         whitespace separated. If we can get them added to other places
> easily
>         then cool.
>         function foo() {
>           //tags: internal, special_tag
>           //summary: foo function
>           ...
>         }
>
>         In XML tags are added under different items as:
>           ...  <tag>internal</tag><tag>special-tag</tag> ...
>         This makes it fairly straightforward to use them in XSD or when
> parsing
>         with code.
>
>         In JSON tags are presented as an array:
>         { ... , tags: ['internal', 'special-tag'], ... }
>
>         Use Case 1:
>         In our map product we have a series of markermanagers that
> control how
>         markers are drawn. One thing they handle is whether and how
> markers are
>         clustered together.
>
>         As a client, when you initialise the map you can specify a
> manager to
>         use. But apart from specifying it,
>         the manager is internal and there is no client API for it. But
> because
>         there are a number of managers they have a documented API. Just
> not for
>         clients to use. So this could be tagged 'internal'.
>
>         Use Case 2:
>         Say use of an object or method is deprecated after V1. It should
> be
>         marked as such in the V2 docs and hidden by default. This item
> could be
>         tagged 'deprecated'.
> }}}

New description:

 The attached patch is made up of the following parts:

 1) fixes to the tree walker to allow the parser to run on non dojo trees
 (also simplifies it)

 2) Adds 'tags' as a special comment field

 3) Allows filtering of what is included in the output files based on the
 tags, private members and can strip source.

 4) Allows configuration of which paths, namespace prefixes and filters are
 run from the command line

 Tags work as follows
 {{{
 Idea:
         Add tags to doc parser. These could be useful for segmenting
 generated
         documentation for different audiences. (eg. internal team vs
 clients,
         contribs vs users)

         When the docparser runs it would produce a set of tags for each
         object/function/var/...

         1. They could be used to filter the parser output before it was
 used in
         the ApiRef so there is no overhead of downloading stuff that is
         never/should never be displayed.

         2. They could be used in the display of documentation in any form,
 or as
         it is converted to another form (XSD).

         In source, tags are specified whereever you can have a summary.
 Comma or
         whitespace separated. If we can get them added to other places
 easily
         then cool.
         function foo() {
           //tags: internal, special_tag
           //summary: foo function
           ...
         }

         In XML tags are added under different items as:
           ...  <tag>internal</tag><tag>special-tag</tag> ...
         This makes it fairly straightforward to use them in XSD or when
 parsing
         with code.

         In JSON tags are presented as an array:
         { ... , tags: ['internal', 'special-tag'], ... }

         Use Case 1:
         In our map product we have a series of markermanagers that control
 how
         markers are drawn. One thing they handle is whether and how
 markers are
         clustered together.

         As a client, when you initialise the map you can specify a manager
 to
         use. But apart from specifying it,
         the manager is internal and there is no client API for it. But
 because
         there are a number of managers they have a documented API. Just
 not for
         clients to use. So this could be tagged 'internal'.

         Use Case 2:
         Say use of an object or method is deprecated after V1. It should
 be
         marked as such in the V2 docs and hidden by default. This item
 could be
         tagged 'deprecated'.
 }}}

--

Comment:

 New parser works differently than this patch. Will add stripping features
 if requested.

-- 
Ticket URL: <http://trac.dojotoolkit.org/ticket/2675#comment:8>
dojo <http://dojotoolkit.org/>
The Dojo UI Toolkit