[TW5] Improving code documentation

[Jed Carty]

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.

[Matabele]

Hi Jed

Aha. Just what's needed ... when it's finished :-)

I'll see what I can do to help out.

regards

[Jeremy Ruston]

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.

--
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 tiddlywikide...@googlegroups.com.
To post to this group, send email to tiddly...@googlegroups.com.
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.
For more options, visit https://groups.google.com/d/optout.

[Matabele]

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

[Jeremy Ruston]

Hi Matabele

One of the problems with your approach: that many of the files in question are fairly long.

Apologies, I wasn’t clear: part of the proposal is to slice all the core JS tiddlers into separate, tiddler-size files. Then we won’t need to have embedded code docs, we can keep the docs as separate, translatable tiddlers, and have lots of flexibility about how/when we ship the docs.

Another disadvantage: the code comments would need fleshing out, adding to the size of the empty edition.

Just to emphasise, my proposal here has the side effect of stripping the code docs out of the empty edition

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.

I’m kind of thinking that under this plan maybe I’d switch to doing my own editing in TW itself, for exactly your reasons: I can easily customise an editing environment that reflects the tasks I need to do regularly. Plenty of people do all of their JS editing in the browser, and some of them do it in TW. 

Best wishes

Jeremy.

To view this discussion on the web visit https://groups.google.com/d/msgid/tiddlywikidev/80cc8535-c366-4834-91f1-8c23fed923ca%40googlegroups.com.

[Matabele]

Hi Jeremy

Re: Editing in TW.

There are other advantages here, not only could the documentation be supplied as a plugin, but so could a complete editing environment. This environment might be customised to highlight the TW code style (jslint like), and might include a mechanism for auto-formatting to standard TW style code.

regards

[Felix Küppers]

Hi Jeremy,

now I got totally confused. You say

Apologies, I wasn’t clear: part of the proposal is to slice all the core JS tiddlers into separate, tiddler-size files. Then we won’t need to have embedded code docs, we can keep the docs as separate, translatable tiddlers, and have lots of flexibility about how/when we ship the docs.

You want to split up the actual source code to achieve better documentation? So e.g. widget.js will become several smaller javascript modules? Or were you just referring to the way the documentation is done – so the actual code is not sliced – and only the docs are presented "one tiddler per function".

-Felix

[Mat]

@Jed

Might you perhaps re-use your work on that CSS tool you made, to find and append search words to CSS definitions etc? 

<:-)