#2675 closed enhancement (wontfix)
Multiple updates for doc parser
Reported by: | Owned by: | Neil Roberts | |
---|---|---|---|
Priority: | high | Milestone: | future |
Component: | Doc parser | Version: | 0.4.2 |
Keywords: | Cc: | [email protected]… | |
Blocked By: | Blocking: |
Description (last modified by )
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'.
Attachments (4)
Change History (12)
Changed 14 years ago by
Attachment: | dojo_doc_parser_patch added |
---|
comment:1 Changed 14 years ago by
comment:2 Changed 14 years ago by
Note that this patch applies to HEAD after [7844] which fixes some issue with parsing dojo.declare() statements.
comment:3 Changed 14 years ago by
Apologies if I'm being dense, but your patch cites (revision 656). That's obviously not a dojo SVN revision #. If I switch that to 7844, tortoiseSVN informs me the "The patch seems outdated" .. the file line and patch line do not match. I've got todays HEAD, but I've also tried against 0.4.2
comment:4 Changed 14 years ago by
Possibly the patch was from our vendor branch, I did check it applied against head but who knows what happened, I have attached three new patches which separately add: tags, filters and namespace setting. These are definitely against head as of 3 mins ago [7906].
Changed 14 years ago by
Attachment: | parser_filters_diff added |
---|
Patch to add filter options to the parser
Changed 14 years ago by
Attachment: | parser_namespace_diff added |
---|
adds support for user definable namespaces/paths
Changed 14 years ago by
Attachment: | parser_tags_diff added |
---|
adds custom tags for filtering documentation
comment:6 Changed 13 years ago by
Milestone: | → 1.1 |
---|
Neil, please decide what to do with this prior to 1.1 final.
comment:7 Changed 12 years ago by
Milestone: | 1.2 → future |
---|
defer dormant enhancements to "future" (they don't look like they're getting fixed soon so might as well mark as such)
comment:8 Changed 12 years ago by
Description: | modified (diff) |
---|---|
Resolution: | → wontfix |
Status: | new → closed |
New parser works differently than this patch. Will add stripping features if requested.
Since some people have asked, I've added some brief docs on how to use the changes here. These should be added to http://dojo.jot.com/WikiHome/DocParserInstructions if/when the patch is accepted. Comments and suggestions are welcome!
--filter_source
will exclude any source snippets from the JSON and XML output.--filter_private
will exclude any variables or methods named with an '_' prefix from the JSON and XML output.Tags
Tags you can add to your code like this:
You can add them anywhere you can put a summary note currently (where that is we'll leave as an exercise for the reader). They can be letters, numbers and underscores and are case sensitive. These get added to a tags block in the JSON and XML output, and are currently unused by anything.
However, you can filter the docparser output using tags. For example:
--filter_exclude_tags=deprecated
--filter_include_only_tags=new