> we should only use/allow a very limited subset of wiki syntax in
> order not to obscure the documentation with excessive markup
I absolutely agree.
Question is, what should that minimal subset be, and which patterns do
we need.
The most important part, of course, are function signatures.
Since JSDoc* is the traditional choice here, let's see what that would
look like:
/**
* <summary>
*
* @param {<type>} <name> <description>
* @returns {<type>} <description>
*
* <details>
*/
function foo( ... ) { ... }
While this often isn't very readable (esp. WRT distinguishing argument
names and descriptions), the basic structure - flag plus slots for type,
name and description - is useful.
So here's what I imagine we might end up with:
//# !foo
// <summary>
//#
//# * param <name> (<type>): <description>
//# * returns (<type>): <description>
//#
//# <details>
function foo( ... ) { ... }
(Note: Using individual "//" and "//#" markers instead of "/* ... */"
because that's what Cook understands.)
As for supported markup, I think headings, lists, italics, monospace and
links would probably suffice for starters.
(Note that internal links don't seem to be supported yet.)
We should agree on these basics ASAP so we can start on the actual
documentation.
-- F.
* http://jsdoc.sourceforge.net/
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"TiddlyWikiDev" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to
[email protected]
For more options, visit this group at
http://groups.google.com/group/TiddlyWikiDev?hl=en
-~----------~----~----~----~------~----~------~--~---
