Hi all,
I was looking through the docmaker and the documentation in the header files. There are a few
things I noted:
(1)
There are two formats for markup tags:
<Section> and @Section
There are also two formats for comment blocks:
/*****************************/
/* */
/* */
/*****************************/
/************************************ (at least 2 asterisks)
*
*
*
*/
I suggest replacing these with a single format that is easy to write.
(2)
I have previously discussed (with Werner)
about whether to retain the current markup
tags.
I believe these should be selectively retained, because this (a)
makes it easy to differentiate
between sections, and
(b) this may prove useful in the future if there is an additional requirement.
(3)
For each section of a comment block, currently there is only a starting tag, like <Section>.
I suggest adding an ending tag like </Section> so that anything between these tags can be
directly parsed as markdown.
(4)
Code blocks in comments are currently wrapped in curly brackets. This can be either replaced
with the triple backticks (```) in the documentation itself, or this replacement can be handled by
the modified docmaker depending on the requirement of the to-html converter.
(5)
Nikolaus had suggested looking at Rustdoc, which uses Markdown to generate static docs.
I would like to discuss about this.
The problem with going full markdown like Rustdoc (see [1] for an example) is that this will
remove all information about what section a data type belongs to.
We could solve this by adding a <Section> tag first and then having markdown after it. This is
another possible solution, where everything after the Section tag will be directly parsed as
markdown (except headings).
(The only problem I see here is people forgetting to add the space after # in headings).
Programmatically, this would be no different from having markup tags. This is because for most
cases, we would need to convert H1/H2 headings to H2/H3, because in most converters, H1 is
used for page title, and all sections after use H2/H3 and so on.
Please let me know your thoughts while I come up with a few examples, and then we can decide
on a format.
Thanks for reading the long mail, and have a nice day :)
--