Hi Jeremy One of the problems with your approach: that many of the files in question are fairly long. I often search for a function on Github, browse to the file, then have to scroll down through the file to find the relevant function. I then commonly have to follow functions calls within the function to other parts of the file before I can work out what to expect. This, when I most often need only details of the number and type of input parameters, a description of what they are, and details of what's returned.
Another disadvantage: the code comments would need fleshing out, adding to the size of the empty edition. Perhaps, rather, the detailed comments should be moved to another wiki (perhaps a special edition where the comments are interspersed with code), where it is easy to drill down to the relevant comment. Once this were done, many of the comments in the core of the empty edition could be deleted, but at the cost of introducing synchronisation problems between code and documentation. Here, wikitext might be of assistance; if a link to the relevant documentation were provided above the function in the empty edition, this could point to the relevant section of a core documentation plugin, if installed i.e. Jed's documentation needs to be set up to function in the form of a core documentation plugin. regards On Sunday, 31 January 2016 14:50:36 UTC+2, Jeremy Ruston wrote: > > In terms of code documentation, my original idea was to format the code > comments in wikitext, and view the code through a special parser that > syntax highlights the code and formats the comments as sticky notes. > > Here’s a screenshot showing it working in TW5 from June 2012 (!): > > > > https://github.com/Jermolene/old.jermolene.github.com/tree/08cfe90e50563d8bdb2c5c40423eb44395e028ed > > Now, I’m keener on the idea of splitting all the source files into > tiddlers; the smallest chunk of JS code that be documented as a unit. So > we’d have tiddlers for individual function definitions, and split off the > docs into separate tiddlers that would be linked together by a naming > convention. This approach reflects my opinion that software development is > needlessly shackled to the conventions and limitations of files and file > systems. It seems like a historical accident that we experience software > source code primarily as a folder full of files, with a hierarchical > structure that never seems sufficient to express the inner logic of the > thing. > > Best wishes > > Jeremy. > > > On 31 Jan 2016, at 12:36, Matabele <[email protected] <javascript:>> > wrote: > > Hi Jed > > Aha. Just what's needed ... when it's finished :-) > > I'll see what I can do to help out. > > regards > > On Sunday, 31 January 2016 13:46:30 UTC+2, Jed Carty wrote: >> >> This may exist somewhere I haven't seen yet, but I keep forgetting how >> the code is organized so I am putting together a searchable wiki that lists >> all of the files and functions in the tiddlywiki code base. It is only the >> framework and is going to take a while to finish. Luckly now that we have >> some twederation things set up other people can help. If you want to help >> make your own copy of http://twfilestructure.tiddlyspot.com/ and I can >> collect any updates to it. >> > > -- > You received this message because you are subscribed to the Google Groups > "TiddlyWikiDev" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected] <javascript:>. > To post to this group, send email to [email protected] > <javascript:>. > Visit this group at https://groups.google.com/group/tiddlywikidev. > To view this discussion on the web visit > https://groups.google.com/d/msgid/tiddlywikidev/bebc64c4-44c0-4a0e-ad65-410b57b76e6b%40googlegroups.com > > <https://groups.google.com/d/msgid/tiddlywikidev/bebc64c4-44c0-4a0e-ad65-410b57b76e6b%40googlegroups.com?utm_medium=email&utm_source=footer> > . > For more options, visit https://groups.google.com/d/optout. > > > -- You received this message because you are subscribed to the Google Groups "TiddlyWikiDev" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/tiddlywikidev. To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywikidev/80cc8535-c366-4834-91f1-8c23fed923ca%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.
