Is it possible to have the C++ docs show the source again?

General Feedback & Requests
1

A few months ago, the C++ docs always showed the source which was super useful.

Now when I look up a function I have to go through a bunch of tedious steps and then eventually about 30 seconds later it’ll find the source in Visual Studio. It makes it really tedious to analyze how things are put together.

2

Maybe the code changes too quickly so that maintaining it up to date in the docs would bind too much resources…

3

We have an internal discussion going about this very topic. We removed it because the source is readily available and we were worried it would become confusing with the source and example code on the same page. I think we may end up adding it back unless we find a better solution that addresses all concerns (in fact, we may have already added it back for the next release). We would rather err on the side of giving everyone what they want than holding back to avoid potential confusion.

4

I think code snippits are very useful for overridable functions to see default behavior, like CalcCamera in actors

5

@

A thought that just came across my mind, thinking about this.
As far as I know, you guys use specific formatting rules for header comments so the documentation tool can more or less extract them automatically.

Would it be possible to implement the following:

  • Define a “token” keyword. Lets say we choose “$CodeSnippet$” and “$/CodeSnippet$”
  • Use them in pairs throughout the source code in a commented form.
  • Extend/make a tool that extracts the content between the token tags and include it into the documentation.

Like:


void MainVertexShader(
	FVertexFactoryInput Input,
	OPTIONAL_VertexID
	out FLightMapDensityVSOutput Output
	)
{
	FVertexFactoryIntermediates VFIntermediates = GetVertexFactoryIntermediates(Input);
	float4 WorldPosition = VertexFactoryGetWorldPosition(Input, VFIntermediates);
	float3x3 TangentToLocal = VertexFactoryGetTangentToLocal(Input, VFIntermediates);

        // $CodeSnippet$
	FMaterialVertexParameters VertexParameters = GetMaterialVertexParameters(Input, VFIntermediates, WorldPosition.xyz, TangentToLocal);
	WorldPosition.xyz += GetMaterialWorldPositionOffset(VertexParameters);
        // $/CodeSnippet$

	Output.WorldPosition = WorldPosition;
	ISOLATE
	{
		float4 RasterizedWorldPosition = VertexFactoryGetRasterizedWorldPosition(Input, VFIntermediates, Output.WorldPosition);
		Output.Position = mul(RasterizedWorldPosition, View.TranslatedWorldToClip);
	}
	Output.FactoryInterpolants = VertexFactoryGetInterpolantsVSToPS(Input, VFIntermediates, VertexParameters);

	OutputVertexID( Output );
}

Being comments, they would be ignored by the compiler.
If used sensibly, it shouldnt clutter up the source code too much.
You could also use a “flag” in the function header comments format to indicate that the function code is to be included in the documentation in its entirety…

PS: I could easily make such a tool, just not (easily) in C++ :slight_smile:

6

+1 for putting source code back into docs, it’s so much easier than searching through the source/github.
If it’s a question of readability, no problem having the source code hidden until manually expanded.

7

Oh, I just noticed that… there is not source anymore, huh… that was super fast tool, on my computer, opening class using VS right click takes a few minutes. +1 for putting it back :slight_smile:

8

I’m 99.9% sure the docs are auto generated based on the comments in the code using some tool like DOXYGEN. There’s a flag to include source in the docs along with the docs on what the parameters do, etc… They must have flipped that switch off recently. It shouldn’t be an issue to reenable it.

Especially now that Unreal Engine is free.