supercollider-common 1:3.6.3~repack-5 / usr / share / SuperCollider / SCClassLibrary / SCDoc / TODO

TODO
----

- should we allow *.ext.schelp to add to related:: and categories:: ?

- clean up old-help compatibility, do we really need it in both HelpBrowser-goTo and SCDoc.findHelpFile?

- HelpBrowser: clean up openNewWindows setting. only have a single class variable?

- how to merge methods docs for overwritten methods? replace the whole method doc, or add to it?

- copymethod::
  should we warn if the method signature is not the same as the target method, if any?
  what to do with method argstring when copying from non-class/instance to class/instance and vice versa?
  should we cache last used parse tree in the common case of copying many methods from the same source?

- Additional triggers for dest-doc should update:
   - implementing class changed
        if(doc.redirect.notNil and: {doc.implKlass != doc.klass.tryPerform(doc.redirect.asSymbol)})
        but this only works if doc.implKlass was the *old* implementing class..
        so in this case we actually need to store stuff on disk.
   - another docs metadata changed (for link:: titles)
     not sure what to do about that.. actually it must be solved by a dependency system.
     docs that links to other docs has those as dependencies.
   - class hier changed (for classtree:: tag)
     this means we need to know if a doc uses classtree::, could be marked in the SCDocMapEntry.
     also we need to store last class hier on disk, or just always re-render docs that use classtree:: (once per session)

- SCDoc.cpp: replace node->children with a linked list (node->next and node->tail)
  instead of realloc'ing? same for text strings instead of using strmerge?
  or realloc in blocks?

- also write the arg string and the first line of each method description to a methods.js,
  to show in Search.

- private:: now counts as a subsection (like method:: and copymethod::)
  this means it is a section that can't have any text in it, meaning it needs
  to come after any section text.
  an alternative would be to use the syntax: class/instancemethods optprivate subsections
  but that would mean it *must* come right after the class/instancemethods section header.
  This would be a lot better actually, since we can then collect all private methodnames
  easier instead of having to scan the whole section!

- deprecate keyword:: and introduce a keywords:: in header only?
  one could then optionally use anchor::kw_word:: to set kw locations in the doc.
  the idea is that it would speed up metadata parsing, but I'm not sure it would.

- error lines are not always correct, probably because many tags eat trailing newlines.
  but if we eat newlines before a tag, it will break EOL termination detection..

- move inherit-mets from JS to renderer. get rid of docmap.js loading in docs.
  Export those lists locally for each class doc instead.
  OTOH, that means that we write the whole Object method list into *each* class doc!
  Not so nice.. so keep it like this for the moment!

  (then, do we really need the subclasses/superclasses in docmap.js?
  yes, maybe for method search results ("class A inherited by B, etc..")
  but then, at least only write it to docmap.js, no need to store it in SCDocMapEntry.)

* Adjust or deprecate all old classes and methods related to help:

Classes:

    AutoClassHelper
    HelpSearchResult
    UGenHelper
    AutoClassHelperTest
    TopicHelper
    Help
    ClassHelper
    Helper

Methods todo:
    *Platform, Platform : helpDir - deprecate in favor of SCDoc.helpTargetDir ?
    PathName : helpFilesDo
    Help, *Help : findHelpFile - Used by SCDoc to get old help, fix this when all old help is converted
    Help : findHelpFileOrElse
    Class, Method : hasHelpFile - in SCDoc all classes has a helpfile - even if it's an autogenerated stub

Methods to deprecate?
    AutoClassHelper, ClassHelper, *Help, TopicHelper, UGenHelper : makeHelp
    Helper : initHelper
    TopicHelper : initTopicHelper
    UGenHelper : initUGenHelper
    *Quarks, Quarks : help
    *Help : makeAutoHelp
    Integer : isHelp
    AutoClassHelper, ClassHelper : initClassHelper

Methods done but could be improved:
    // Class : helpFileForMethod  - FIXME: should jump to method anchor
    // Method : help - FIXME: should jump to method anchor

Also deprecate class.categories since this is now in the helpfiles instead?
(categories can still be reached run-time from SCDoc.documents[path])


IDEAS AND IMPROVEMENTS
----------------------
* description for categories? HelpSource/category_descriptions, example:
  Server>Abstractions: Client-side classes representing server-side stuff
  show in header and category browser/overview..
  extensions should be able to add such descriptions too, but not overwrite existing descriptions?

* comments (* like this? *)

* shortcuts for links to method in class? mlink::Node-set:: -> link::Classes/Node#-set::
or clink::Node#-set:: -> link::Classes/Node#-set:: ?

* render binary op methods differently? like ArrayedCollections ++
we don't want it to display as "++ (aCollection)" do we? rather "++ aCollection" or "this ++ that" or something..
binary ops only uses chars from this list: !@%&*-+=|<>?/


Crazy ideas:

- make a new renderer also in C??
  integrated with sclang that can access the introspection data (classtree and methods).
  it could use the docnode tree directly from the parser instead of going through sclang objects

- or, let both parser and renderer be standalone.
  * introspection data could be provided by a machine-readable file written by sclang
    - class tree, their methods, the filenameSymbol for each class and method.
    
    C classname
        F filenameSymbol
        CM methodname
            F filenameSymbol
            A name defaultvalue
            A etc...
        XM
        IM methodname
            etc...
        XM
        C subclassname
            etc...
        XC
    XC
    
  but then we need also an output mode that generates sclang code for docmap construction.

- even make the whole scdoc thing in C?
  * find all helpsource files and render if newer than html target
  * copy any other files as is
  * write docmap.json and/or docmap.scd for sclang interface, needed by find-help-for-string, etc.

  * docmap is also needed internally by scdoc renderer:
  - document title for links
  - class summary for classtree::
  We could have a mode to only parse the header, and run this first to create the initial docmap.
  then when we parse all docs fully, the other metadata would be filled in (documented methods, keywords, etc)

  * it should be fast enough to render all updated files at startup
  * the process can run in background with .unixCmd, with an action to set helpAvailable=true

...