Make a simple pretty-comment tool
JavaScript(ES6), 418, 237, 233, 236 bytes

f=(s)=&gt;(d='\n//',s.split(d+'\n').map((x,y)=&gt;y%2?'//'+(l=x.slice(2).split(d),t=l.pop().split('*'),l.map((i,j)=&gt;t.map((k,m)=&gt;m==j?k+'/':m&lt;j?k+'|':k.replace(/ /g,'-')+'-').join('')+'&lt;'+i).join(d)+d+t.join('|')+d+t.join('v')):x).join('\n'))


Whew, this is my first submission on CG. Took, I think, a totally different tack from Washington Guedes. Ended up 54 bytes shorter than his first pass. Minifying all this by hand was grueling. My one regret is not being able to eliminate the while loop yet, which would also let me cut the return.

Total rewrite, taking partial inspiration from a couple of the other answers. I got to close the whole thing in maps, making returning much better. The code snippet contains the commented version.

Took a few more bytes off, and made the example operate on itself. (You're gonna need a bigger monitor.) :)

Forgot an entire letter in the spec! Fortunately, adding the leading '&lt;' was a tiny, trivial fix.



var comments = `
//
// New function, declare the comment delimiter
// Chop the string by the fancy comment delimiter
// Iterate over the array.
// Because of how it's delimited, and how JS splits strings, only the even elements will contain fancy comments.
// Add the original comment delimiter to the front of the first line, because join won't.
// we've got a single fancy comment, split it into lines.
// Take the last line, our asterisk template, and split it on the asterisks themselves. We were only gonna replace them anyway.
// Now we get to the real work. Iterate the remaining lines.
// For each chunk of whitespace in the template array, toss a different character on the end based on where we are in the series of lines.
// if we're at the matching asterisk, insert a slash
// Otherwise, if we're at a prior asterisk, add a pipe.
// Finally, replace anything afer the matching asterisk with dashes, join the template, and add it to the line text.
// Join the lines with the delimiter
// Add the pipe line...
// And the v line...
// For odd chunks, just return the chunk.
// Join all the code chunks and autoreturn.
//      *        *               *          *   *     *                     *                    *            *            *          *         *                                        *           *             *          *  *  
//
`
f=(s)=&gt;(d='\n//',s.split(d+'\n').map((x,y)=&gt;y%2?'//'+(l=x.slice(2).split(d),t=l.pop().split('*'),l.map((i,j)=&gt;t.map((k,m)=&gt;m==j?k+'/':m&lt;j?k+'|':k.replace(/ /g,'-')+'-').join('')+'&lt;'+i).join(d)+d+t.join('|')+d+t.join('v')):x).join('\n'))

str = `
//
// This is a test
// with two lines
// actually three
// *  *       *
//
var myCode = function () {

}
// This doesn't cause any trouble.

moreCode(stuff--)

//
// another test?
//  *
//

`
document.getElementById('before').textContent = str;
document.getElementById('after').textContent = f(str);
document.getElementById('self').textContent = f(comments)+'f='+f.toString();
Test cases before:
&lt;pre id="before" style="background:#eef"&gt;&lt;/pre&gt;
Test cases after:
&lt;pre id="after" style="background:#eef"&gt;&lt;/pre&gt;
Self-annotated:
&lt;pre id="self"&gt;&lt;/pre&gt;