Are there conventions for documenting TiddlyWiki code?

#1

I’ll take the function from https://tiddlywiki.com/#Functions as example:

\function myfun(param:"2")
[<param>multiply[1.5]]
\end

If I want to document it, are there any conventions for docs? Are there any tools, like a linter, an automated documentation generator?

I suppose I can use HTML comments, to get something like this:

\function myfun(param:"2")
<!--
Multiply a numeric value by 1.5

Parameters:

param - value to multiply
-->
[<param>multiply[1.5]]
\end

This is a la Python docstrings, with doc inside the function body.

I think JavaScript (albeit wikitext is not JavaScript) puts this before the function body, so it’s rather like

<!--
Multiply a numeric value by 1.5

Parameters:

param - value to multiply
-->
\function myfun(param:"2")
[<param>multiply[1.5]]
\end

This is at least friendlier for oneliner code snippets. But is this the recommended way? Are there any standards at all?

And of course I have to be picky about a wording detail in the docs, due to my limited English knowledge. Quote from https://tiddlywiki.com/#Pragmas :

They (pragmas) can only appear at the start of the text of a tiddler, but blank lines and comments are allowed between them.

If I translate this literally, the “between” part especially, does it mean that the very first function/macro in a tiddler can’t have a HTML comment like above before its definition?

#2

There is a documentation style guide: https://tiddlywiki.com/#Documentation%20Style%20Guide

#3

There is a small performance penalty if the html comment is inside functions or procedures.

In this case the https://tiddlywiki.com/#Functions tiddler is intended to explain, what functions are. It is not intended to describe the myfun(param:"2") function.

So there can be a description about the different elements of the function definition and how they are used.

If the structure is explained there can be a link to eg: Functions (Examples), which contains examples, how to call examples.

So the following can be in Functions

I

image
image1501×179 10 KB

More detailed info can be in “Functions (Examples)”

Hope that makes sense
-m

#4

It is perfectly fine to use comments as follows. But that’s not how we do documentation in the TW docs. We use html-comments in the core UI wikitext. – But it is only used if really important for maintenance.

<!-- asdf -->
\define test() asdf

<<test>>

For code that should be used by users for further testing we use: https://tiddlywiki.com/#Documentation%20Macros and wikitext macros

IMO detailed documentation for wikitext macros is missing atm.

I personally import my Trails-Plugin into tiddlywiki.com to see, where in the TOC tree I am.

For me this helps a lot to define new documentation tiddlers.

image
image1522×561 25.1 KB