I doubt if I'm the only one thinking of this but here goes.
Often when coding an app in an area that needs some prior analysis and math, it's wise to detail in the code's comments just how and why the code is written as it is. Without this info written down, it's hard to get a handle on things a few months - and a few projects ! - after.
But lengthy comments disrupt the amount of code that's visible in one screenfull.
And since source files are little more than text files, you can't put in things like math equations, UML diagrams, circuit diagrams, schematics, orientation arrows, etc without a ridiculous amount of fiddling - e.g. putting numerator, line and divisor on separate lines.
I think what is really needed here is a separate file type that can accommodate equation writing, UML diagrams, circuit diagrams, schematics, etc and which the person examining the code can open on a separate window on their large monitor when they needs to find the computation method used in a project.
Sure, the odd small comment will still be needed within the code but these would now be simply reference points between the code and the info file once the latter has been read and digested.
I've tried searching under "code info(rmation) file" to no avail on Google.
Does anyone else know of any existing file structure that would be incorporatable into projects for the purpose I've described ?
And preferably compatible with the needs of all the major coding languages (i.e. Java, C/C++/C#/Obj C, Ada, Ruby) and their common IDEs.