SCClassLibrary/SCDoc/TODO

   1 TODO
   2 ----
   3
   4 - should we allow *.ext.schelp to add to related:: and categories:: ?
   5
   6 - clean up old-help compatibility, do we really need it in both HelpBrowser-goTo and SCDoc.findHelpFile?
   7
   8 - HelpBrowser: clean up openNewWindows setting. only have a single class variable?
   9
  10 - how to merge methods docs for overwritten methods? replace the whole method doc, or add to it?
  11
  12 - copymethod::
  13   should we warn if the method signature is not the same as the target method, if any?
  14   what to do with method argstring when copying from non-class/instance to class/instance and vice versa?
  15   should we cache last used parse tree in the common case of copying many methods from the same source?
  16
  17 - Additional triggers for dest-doc should update:
  18    - implementing class changed
  19         if(doc.redirect.notNil and: {doc.implKlass != doc.klass.tryPerform(doc.redirect.asSymbol)})
  20         but this only works if doc.implKlass was the *old* implementing class..
  21         so in this case we actually need to store stuff on disk.
  22    - another docs metadata changed (for link:: titles)
  23      not sure what to do about that.. actually it must be solved by a dependency system.
  24      docs that links to other docs has those as dependencies.
  25    - class hier changed (for classtree:: tag)
  26      this means we need to know if a doc uses classtree::, could be marked in the SCDocMapEntry.
  27      also we need to store last class hier on disk, or just always re-render docs that use classtree:: (once per session)
  28
  29 - SCDoc.cpp: replace node->children with a linked list (node->next and node->tail)
  30   instead of realloc'ing? same for text strings instead of using strmerge?
  31   or realloc in blocks?
  32
  33 - also write the arg string and the first line of each method description to a methods.js,
  34   to show in Search.
  35
  36 - private:: now counts as a subsection (like method:: and copymethod::)
  37   this means it is a section that can't have any text in it, meaning it needs
  38   to come after any section text.
  39   an alternative would be to use the syntax: class/instancemethods optprivate subsections
  40   but that would mean it *must* come right after the class/instancemethods section header.
  41   This would be a lot better actually, since we can then collect all private methodnames
  42   easier instead of having to scan the whole section!
  43
  44 - deprecate keyword:: and introduce a keywords:: in header only?
  45   one could then optionally use anchor::kw_word:: to set kw locations in the doc.
  46   the idea is that it would speed up metadata parsing, but I'm not sure it would.
  47
  48 - error lines are not always correct, probably because many tags eat trailing newlines.
  49   but if we eat newlines before a tag, it will break EOL termination detection..
  50
  51 - move inherit-mets from JS to renderer. get rid of docmap.js loading in docs.
  52   Export those lists locally for each class doc instead.
  53   OTOH, that means that we write the whole Object method list into *each* class doc!
  54   Not so nice.. so keep it like this for the moment!
  55
  56   (then, do we really need the subclasses/superclasses in docmap.js?
  57   yes, maybe for method search results ("class A inherited by B, etc..")
  58   but then, at least only write it to docmap.js, no need to store it in SCDocMapEntry.)
  59
  60 * Adjust or deprecate all old classes and methods related to help:
  61
  62 Classes:
  63
  64     AutoClassHelper
  65     HelpSearchResult
  66     UGenHelper
  67     AutoClassHelperTest
  68     TopicHelper
  69     Help
  70     ClassHelper
  71     Helper
  72
  73 Methods todo:
  74     *Platform, Platform : helpDir - deprecate in favor of SCDoc.helpTargetDir ?
  75     PathName : helpFilesDo
  76     Help, *Help : findHelpFile - Used by SCDoc to get old help, fix this when all old help is converted
  77     Help : findHelpFileOrElse
  78     Class, Method : hasHelpFile - in SCDoc all classes has a helpfile - even if it's an autogenerated stub
  79
  80 Methods to deprecate?
  81     AutoClassHelper, ClassHelper, *Help, TopicHelper, UGenHelper : makeHelp
  82     Helper : initHelper
  83     TopicHelper : initTopicHelper
  84     UGenHelper : initUGenHelper
  85     *Quarks, Quarks : help
  86     *Help : makeAutoHelp
  87     Integer : isHelp
  88     AutoClassHelper, ClassHelper : initClassHelper
  89
  90 Methods done but could be improved:
  91     // Class : helpFileForMethod  - FIXME: should jump to method anchor
  92     // Method : help - FIXME: should jump to method anchor
  93
  94 Also deprecate class.categories since this is now in the helpfiles instead?
  95 (categories can still be reached run-time from SCDoc.documents[path])
  96
  97
  98 IDEAS AND IMPROVEMENTS
  99 ----------------------
 100 * description for categories? HelpSource/category_descriptions, example:
 101   Server>Abstractions: Client-side classes representing server-side stuff
 102   show in header and category browser/overview..
 103   extensions should be able to add such descriptions too, but not overwrite existing descriptions?
 104
 105 * comments (* like this? *)
 106
 107 * shortcuts for links to method in class? mlink::Node-set:: -> link::Classes/Node#-set::
 108 or clink::Node#-set:: -> link::Classes/Node#-set:: ?
 109
 110 * render binary op methods differently? like ArrayedCollections ++
 111 we don't want it to display as "++ (aCollection)" do we? rather "++ aCollection" or "this ++ that" or something..
 112 binary ops only uses chars from this list: !@%&*-+=|<>?/
 113
 114
 115 Crazy ideas:
 116
 117 - make a new renderer also in C??
 118   integrated with sclang that can access the introspection data (classtree and methods).
 119   it could use the docnode tree directly from the parser instead of going through sclang objects
 120
 121 - or, let both parser and renderer be standalone.
 122   * introspection data could be provided by a machine-readable file written by sclang
 123     - class tree, their methods, the filenameSymbol for each class and method.
 124
 125     C classname
 126         F filenameSymbol
 127         CM methodname
 128             F filenameSymbol
 129             A name defaultvalue
 130             A etc...
 131         XM
 132         IM methodname
 133             etc...
 134         XM
 135         C subclassname
 136             etc...
 137         XC
 138     XC
 139
 140   but then we need also an output mode that generates sclang code for docmap construction.
 141
 142 - even make the whole scdoc thing in C?
 143   * find all helpsource files and render if newer than html target
 144   * copy any other files as is
 145   * write docmap.json and/or docmap.scd for sclang interface, needed by find-help-for-string, etc.
 146
 147   * docmap is also needed internally by scdoc renderer:
 148   - document title for links
 149   - class summary for classtree::
 150   We could have a mode to only parse the header, and run this first to create the initial docmap.
 151   then when we parse all docs fully, the other metadata would be filled in (documented methods, keywords, etc)
 152
 153   * it should be fast enough to render all updated files at startup
 154   * the process can run in background with .unixCmd, with an action to set helpAvailable=true
 155
 156 ...
 157