docs
docs copied to clipboard
nunit
Internal trace docs incorrectly say the output is sent to the console by default
https://github.com/nunit/docs/wiki/Internal-Trace#design:
By default, all output through InternalTrace is sent to the console, which means it is mixed with other console output. Note that the trace mechanism bypasses NUnit's redirection of output and displays on the actual Console. Of course, if NUnit is being run without a console - from the Gui, for example - the output will be lost.
But the internal trace is saved to files in the working folder and not shown in the console, and it doesn't look like the user has any control over this.
The entire paragraph should be replaced by one which describes the output .log files, right?
It actually says a lot of wrong things. It's written as a spec, describing how we planned (how I planned, in fact) for Internal Trace to work in NUnit 3. However, it was linked from the NUnit Internals page as if it were documentation.
I went ahead and retitled it as a spec, linking it from the Specifications page. The link on the NUnit Internals page is now red. Under the Implemented column on the spec page, I put "Partial?"
to indicate that it's partially implemented IFF the team wants to do more of the stuff that's in the spec. If not, then it should be marked "Yes".
The Specifications page was once an entire section of the wiki - a separate wiki at one time in fact. Before I turned over the project, I went through them and removed everything that was complete, with the exception of those that had not yet been documented. The notion of the "Implemented" column was that we would act differently depending on the value:
Yes Create a documentation page and remove the spec. No Use the spec to implement the feature, document it and remove the spec. Partial Complete the implementation of the feature, document it and remove the spec.
I did quite a lot of this so what you see there is just the remains. Somebody could well take over the job of deciding what to do in each case and cleaning it up.
BTW, I would never put specs in the same wiki as docs again. Trouble is that people find them and get confused.
Looks good now.
When I didn't see trace output, the first place I looked before resorting to Google was https://github.com/nunit/docs/wiki/Console-Command-Line. Could we add a short description there of where the user should expect to see the output?
That makes sense. But I wouldn't close this issue - I think it calls for some decisions and then maybe someone will come along to write an actual doc for how it works. There are a few specs that call for some advanced features we never got to. I didn't want to decide whether you guys would go ahead with them or not, so I left them for followup. It would be great to reach the point where the specification page is no longer there at all!