Inline code in the docs - the correct way

[H. S. Teoh]

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