On Wed, Jan 31, 2018 at 03:40:04PM +0000, Jakub Łabaj via Digitalmars-d wrote:
> What is the current state of the art of writing inline code in the
> documentation?
>
> Wiki says "use `...` instead of $(D ...)":
> https://wiki.dlang.org/Contributing_to_Phobos#Documentation_style.
>
> Some arguments made here:
> https://github.com/dlang/phobos/pull/5183#issuecomment-281895450
> suggest that backticks, among others, may not work well with
> cross-references as they may contain a code of a different language
> than D.
>
> Still, pretty recent PRs suggest that backticks should be used, but
> only for single words:
> - https://github.com/dlang/phobos/pull/5801
> - https://github.com/dlang/phobos/pull/5970
>
> I thought of updating the wiki to match the apparent consensus in this
> regard but wanted to make sure if it's really the way to go.
AFAIK, backticks is preferred because $(D ...) syntax is noisier, and
harder to read in the source code. But otherwise, the two are
equivalent. (In fact, backticks translate directly into $(D ...) in the
ddoc code. They are just syntactic sugar.)
But if your code snippet is longer than a line, you should use inline
code block syntax:
/**
blah blah discussion here
----
/* code here */
void main()
{
...
}
----
blah blah discussion here
*/
T
--
In a world without fences, who needs Windows and Gates? -- Christian Surchi
