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

General Feedback & Requests
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: