How can I build an inline documentation utility?

Question

I often have a large function to which I add inline comments, but then I can't see the forest for the trees. How can I make a tool that extracts the comments and tokens within them to generate an overview or structured outline of the large complex function? For instance:

 BigNastyFunction[input_List, xSpecArg_, ySpecArg_, OptionsPattern[]] := 
 Module[
 {
    (*1:1 Local variables*)
   data, ySpecContinousQ, xSpecContinousQ, groupsQ, joinedCounts, colors, ymin, ymax, xmin, 

   (*1:2 Option variables*)
   axesLabelsQ, barOrigin, background, diskSizeScaling, displayFunction, frameQ
 }

  (*2:1 Check for null Input*)
  If[times === {}, Return[$Failed]];

  (*2:2:1 Check for groups *)
  check1 = Depth[input] === 4;  
  (*2:2:2 Check for nongroups *)
  check2 = Depth[input] === 3;  

  etc...

Would be transformed into something like:

Outline of BigNastyFunction

Part 1.

.....Step 1. Local variables

.....Step 2. Option variables

Part 2.

.....Step 1. Check for null Input

.....Step 2.

..........a) Check for groups

..........b) Check for nongroups

Answer 1

I would suggest something more simple-minded than Rolf's sophisticated implementation:

Clear[extractComments];
extractComments[boxes_] :=
  StringJoin@
    Riffle[
      Cases[boxes, 
          r : RowBox[{"(*", ___, "*)"}] :> 
              StringJoin@Cases[r, _String, Infinity], Infinity],
      "\n"];

and the palette:

CreatePalette[
  Button["Comments",
    With[{read = NotebookRead[SelectedNotebook[]]},
      SelectionMove[SelectedNotebook[], After, Cell];
      NotebookWrite[SelectedNotebook[], Cell[extractComments[read]]]
    ]
  ]]

You select your function's cell and press the "Comments" button. This seems to work in simple cases I tested. You can modify the extractComments function to implement more complex logic that would categorize the comments according to their hierarchy etc.

Answer 2

OK, FrontEnd: After creating the "overview" button below just click first on your function definition and then on the button and under the function definition you will get (nearly) what you want, i.e. :

Part 1.

Step 1. Local variables

Part 1.

Step 2. Option variables

Part 2.

Step 1. Check for null Input

Part 2.

Step 2.:1 Check for groups

Part 2.

Step 2.:2 Check for nongroups

  CreatePalette@Cell[BoxData[
 ButtonBox["overview",
  ButtonFunction:>Block[{$CellContext`com}, SelectionMove[
          SelectedNotebook[], All, CellContents]; $CellContext`com = 
     ExportString[
       StringDrop[
        Apply[StringJoin, 
         StringCases[
          Apply[StringJoin, $CellContext`RER = ReplaceRepeated[
                 NotebookRead[
                  InputNotebook[]], RowBox[
                   Condition[
                    Pattern[$CellContext`x, 
                 BlankSequence[]], 
                Not[
                 FreeQ[$CellContext`x, RowBox]]]] :> Apply[RowBox, 
                   ReplaceAll[{$CellContext`x}, RowBox[{
                       Pattern[$CellContext`y, 
                        BlankSequence[]]}] :> $CellContext`y]]]], {
          StringExpression["(*", 
             Shortest[
              Pattern[$CellContext`i, 
                   Blank[]]], ":", 
                 Shortest[
                  Pattern[$CellContext`j, 
               BlankSequence[]]], 
             Shortest[
              Pattern[$CellContext`str, 
                   BlankSequence[]]], "*)"] :> {
                 StringExpression["\nPart ", $CellContext`i, 
                  StringJoin[".\n", "Step "], $CellContext`j, 
                  "."], $CellContext`str}}]], 1], "Text"]; SelectionMove[
          SelectedNotebook[], After, Cell]; NotebookWrite[
          SelectedNotebook[], 
          Cell[$CellContext`com, "Text"]]],
  Evaluator->Automatic]]]