version(StdDoc)

[H. S. Teoh]

On Fri, Nov 23, 2018 at 09:43:01PM -0700, Jonathan M Davis via Digitalmars-d-learn wrote:
[...]
> Honestly, I would argue that if you have multiple versions of the
> documentation, then there's a serious problem. The documentation
> shouldn't be platform-dependent even if the symbols are. Even if the
> documentation needs some extra notes for a specific platform, it
> should all be in one documentation block that anyone using the symbol
> can read. Providing different documentation for different platforms
> just leads to folks not understanding how the symbol differs across
> platforms, leading to code that is even more platform-dependent when
> it really should be as platform independent as possible.

Actually, what would be ideal is if each platform-specific version of
the symbol can have its own associated platform-specific docs, in
addition to the one common across all platforms, and the doc system
would automatically compile these docs into a single block in the
output, possibly by introducing platform specific sections, e.g.:

Code:
	/**
	 * Does something really fun that applied across platforms!
	 */
	version(Windows)
	{
		/**
		 * On Windows, this function displays a really funny
		 * icon!
		 */
		int fun(int a) { ... }
	}
	version(Linux)
	{
		/**
		 * On Linux, this function displays a funny penguin!
		 */
		int fun(int a) { ... }
	}

Doc output:
	int fun(int a)

	Does something really fun that applied across platforms!

	Windows notes: On Windows, this function displays a really funny
	icon!

	Linux notes: On Linux, this function displays a funny penguin!


If the function signatures are different, then it should be displayed as
"overloads", as Adam suggested. Maybe something like this:

Code:
	/**
	 * This function takes a different parameter depending on the
	 * OS.
	 */
	version(Windows)
		int fun(int x) { ... }
	version(Linux)
		int fun(long x) { ... }

Output:
	int fun(int x)		// on Windows
	int fun(long x)		// on Linux

	This function takes a different parameter depending on the OS.


[...]
> As such, I'm not sure that the fact that ddoc forces you to have a
> separate set of declarations just for the documentation is really a
> bad thing. It puts all of the documentation in one place.

It's a bad thing to separate the docs from the actual code, because then
the two are liable to go out-of-sync with each other. It's even worse
when the docs document a fake declaration that isn't actually part of
the real code. Then the docs won't even show the right declaration when
the code changes, and users won't even realize what has happened.


> The bigger problem IMHO is how -D affects the build. Both it and
> -unittest have the fundamental problem that because they create their
> own version identifiers, they really shouldn't be part of the normal
> build, and yet the way that they're set up to be used, it's as if
> they're expected to be part of the normal build - with -D just causing
> the compiler to generate the documentation in addition to the binary,
> and -unittest making the unit tests run before main rather than
> replacing main.
[...]

You can argue for it both ways.  Having the compiler generate docs per
compilation isn't necessarily a bad thing -- it ensures the docs are
up-to-date.  Running unittests also isn't necessarily a bad thing,
though I agree it's sorta weird that unittests are setup to run before
the main program. Technically, you want to run unittests first,
independently of main(), which should be put in a separate executable.
But you can argue for it both ways.

For larger projects, it does make more sense for unittests to be put in
a separate executable and run separately.  But for small programs,
especially when you're coding-compiling-testing, it's handy to have
unittests automatically run before main(), so that any regressions are
quickly noticed and fixed.  This doesn't make sense for larger programs,
e.g., in my Android project, I really want unittests to run on the host
system where possible, not as part of the APK installed to the device,
because it's much easier to debug on the host system than to deal with
crashlogs and remote debugging on the target machine.

(Of course, deploying unittests to the final execution environment also
has its value. But not as part of the main executable, since tests
should be run only once, not every time you invoke the executable, which
depending on your application could be multiple times during a typical
usage session.)


> As for the issue of versioning the documentation, I don't really see a
> clean one. Having the documentation build affected by version and
> static if and the like causes some problems, but having it ignore them
> would likely cause other problems. Regardless, I suspect that having
> the version identifiers and static ifs be ignored almost requires a
> separate tool from the compiler (such as Adam's documentation
> generator or ddox), because it's pretty clear that ddoc was set up to
> generate the documentation for symbols as the compiler compiles them,
> whereas a tool that ignored version identifiers and static ifs would
> be processing the file quite differently.
[...]

There may be a point to generating docs only for the executable that's
being built -- if you configure your versions and static ifs for a
specific customer, say, then you ship exactly that version of the docs
to them.  However, in this day and age where everyone expects online
docs, you really want your docs on your website to include *every*
version of your code that they might encounter. You may wish the
separate it so that the user can select which version(s) they are
interested in, but one would expect you want full docs for every
possible version configuration.

Otherwise you end up needing silly hacks like version(Std_ddoc) just to
get the HTML to show up right, where it isn't actually the symbol that
will be compiled, and worse, the docs are now separate from the
implementation, and the two are liable to go out-of-sync. History has
shown that when the docs aren't a part of the code, they tend to get
neglected and treated as an afterthought, or worse yet, as an unwanted
additional burden that everyone tries to avoid updating.  Needing to
update docs on a declaration completely separate from the code being
changed, that the person making the change may not even be aware of, is
very bad in this regard.


T

-- 
Heuristics are bug-ridden by definition. If they didn't have bugs, they'd be algorithms.