My impression of ROOT Automatic Document Generation

From: Terrence Brannon (brannon@quake.usc.edu)
Date: Fri Jun 27 1997 - 04:51:15 MEST


Says "http://hpna49-7.cern.ch/Documentation.html"

"Automatic Document Generation saves developers enormous amounts of
time and effort by providing instant, detailed and always up to date
information on the internals of the code."

Actually, putting all of the documentation for a complex member
function at the top is very unhelpful to understand it. It is much
better that each complex part have documentation and preferably that
each complex part be a "fold" in a folded Emacs buffer.

Therefore, preferably, ROOTdoc would pick commentary out throughout a
member function as opposed to just the top. However, then explanation
of small details such as logic flow would also get put in the
documentation. 

As an example, just look at this complex member function and honestly
ask yourself whether seeing all the documentation at top is best:

void
G_Info::create_main_window()
{
  // 1: Create main application window and all global X-related
  // quantities:
  //
  // a: create a base frame (base_frame)
  // b: create a filter panel (filter_panel)
  // c: create a grab PANEL_BUTTON (no variable bound) on filter_panel
  // d: create a menu of actions (file_menu)
  // d1: link menu of actions to an Images PANEL_BUTTON
  // e: create a menu of filter actions (filter_menu)
  //    ...currently LOWPASS, SEPCONV, 2DCONV
  // f1: link these actions to a PANEL_BUTTON labeled Filters
  // g: create a Do panel button (no menu)
  // h: create a blackboard PANEL_BUTTON with a menu of blackboard
  // options. This button is labelled "Info"
  // i: create a Quit panel button
  // j: create 3 check boxes
  //  j1: display
  //  j2: crop
  //  j3: replace source
  // k: create a message_text window (message_text)
  // l: create a PANEL_SLIDER to adjust brightness (brightness_slider)
  //
  // 2: get information on the display, screen, and visual
  // 3: make colormaps
  // 4: get the graphic context

  Panel		filter_panel;
  Canvas	source_canvas;
  Xv_window	source_canvas_pw, result_canvas_pw;
  Menu          file_menu, filter_menu, blackboard_menu;
  
  base_frame = xv_create((int)NULL, FRAME_BASE, 
			 XV_LABEL, "Seemore",
			 0);
  
  
  filter_panel = xv_create(base_frame, PANEL, 
			   XV_HEIGHT, 70,
			   XV_WIDTH, 620, 
			   0);
  
  xv_create(filter_panel, PANEL_BUTTON,
	    PANEL_LABEL_STRING, "Grab",
	    PANEL_NOTIFY_PROC, grab_button_callback,
	    0);
  
#define LOAD_GENERIC "Load..."
#define LOAD_DB "Load from database..."
#define SAVE_TO_FILE "Save..."
#define EXPORT_TO_XV "Export to xv..."
#ifdef COM
#define ARCHIVE_SOURCE "Archive Source"
#define ARCHIVE_RESULT "Archive Result"
#endif COM
  
  file_menu = (Menu)xv_create(XV_NULL, MENU,
			      MENU_STRINGS, 
			      LOAD_GENERIC,
			      LOAD_DB,
			      SAVE_TO_FILE,
#ifdef COM
			      ARCHIVE_SOURCE,
			      ARCHIVE_RESULT,
#endif COM
			      EXPORT_TO_XV,
			      /* must have this NULL at end of list */
			      NULL,
			      MENU_NOTIFY_PROC, file_menu_callback,
			      NULL);
  /* link menu to button */
  xv_create (filter_panel, PANEL_BUTTON,
	     PANEL_LABEL_STRING,   "Images",
	     PANEL_ITEM_MENU,    file_menu,
	     NULL);
  
#define LOWPASS "Lowpass..."
#define SEPCONV "Separable Convolution..."
#define CONV "2-D Convolution..."
  
  filter_menu = (Menu)xv_create(XV_NULL, MENU,
				MENU_STRINGS, 
				LOWPASS,
				SEPCONV,
				CONV,
				/* must have NULL at end of list */
				NULL,
				MENU_NOTIFY_PROC, filter_menu_callback,
				NULL);
  /* then menu to button */
  xv_create (filter_panel, PANEL_BUTTON,
	     PANEL_LABEL_STRING,   "Filters",
	     PANEL_ITEM_MENU,    filter_menu,
	     NULL);
  
  xv_create(filter_panel, PANEL_BUTTON,
	    PANEL_LABEL_STRING, "Do",
	    PANEL_NOTIFY_PROC, do_button_callback,
	    0);
  
#define PRINT_BLACKBOARD "Print Blackboard"
#define ERASE_BLACKBOARD "Erase Blackboard"
#define PRINT_HANDLES "Print Handles"
  blackboard_menu = 
    (Menu)xv_create(XV_NULL, MENU,
		    MENU_STRINGS, 
		    PRINT_BLACKBOARD,
		    ERASE_BLACKBOARD,
                    PRINT_HANDLES,
		    NULL,
		    MENU_NOTIFY_PROC, blackboard_menu_callback,
		    NULL);
  xv_create (filter_panel, PANEL_BUTTON,
	     PANEL_LABEL_STRING,   "Info",
	     PANEL_ITEM_MENU,    blackboard_menu,
	     NULL);

  xv_create(filter_panel, PANEL_BUTTON,
	    PANEL_LABEL_STRING, "Quit",
	    PANEL_NOTIFY_PROC, quit_button_callback,
	    0);
  
  xv_create(filter_panel, PANEL_CHECK_BOX, 
	    PANEL_CHOICE_STRINGS, 
	    "Display", 
	    NULL,
	    PANEL_VALUE, int(display_flag),
	    PANEL_NOTIFY_PROC, display_checkbox_callback,
	    NULL);
  
  xv_create(filter_panel, PANEL_CHECK_BOX, 
	    PANEL_CHOICE_STRINGS, 
	    "Crop", 
	    NULL,
	    PANEL_VALUE, int(crop_flag),
	    PANEL_NOTIFY_PROC, crop_checkbox_callback,
	    NULL);

  replace_source_checkbox =
    xv_create(filter_panel, PANEL_CHECK_BOX, 
	      PANEL_CHOICE_STRINGS, 
	      "src<-", 
	      NULL,
	      PANEL_VALUE, 0,
	      PANEL_NOTIFY_PROC, replace_source_checkbox_callback,
	      NULL);


  message_text = xv_create (filter_panel, PANEL_TEXT,
			    PANEL_LABEL_STRING,   "",
			    PANEL_VALUE,   "Welcome to Seemore!",
			    PANEL_VALUE_DISPLAY_LENGTH, 42,
			    PANEL_NEXT_ROW, -1,
			    NULL);
  brightness_slider = xv_create (filter_panel, PANEL_SLIDER,
				 PANEL_LABEL_STRING,   "Brite",
				 PANEL_MIN_VALUE,   0,
				 PANEL_MAX_VALUE,   100,
				 PANEL_VALUE,       0,
				 PANEL_NOTIFY_PROC, brightness_slider_callback,
				 PANEL_NOTIFY_LEVEL, PANEL_ALL,
				 NULL);
  
/*  XI.display = (Display *)xv_get(source_canvas_pw, XV_DISPLAY);*/
  display = (Display *)xv_get(base_frame, XV_DISPLAY);
  screen = DefaultScreen(display);
  
  visual = DefaultVisual(display, screen);
  visual_depth = DefaultDepth(display, screen);
  
  /* keep this for reference */
  if (G.visual_depth == 1) {
    /* must be staticgray--use black and white */
    cerr << "weird--depth is only 1\a\n";
  }
  /* see which visuals are available */
  char *visual_class[] = {
    "StaticGray",
	  "GrayScale",
    "StaticColor",
    "PseudoColor",
    "TrueColor",
    "DirectColor"
    };
  XVisualInfo visual_info;
  int default_visual;
  cout << "X Visuals:\n  ";
  for(int i=0; i<6; i++) {
    if(XMatchVisualInfo(G.display, G.screen, G.visual_depth, 
			i, &visual_info)) {
      cout << visual_class[i] << " ";
      if (visual_info.visual == G.visual) {
        default_visual = i;
      }
    }
  }
  int *depths, depth_count = 0;
  depths = XListDepths(G.display, G.screen, &depth_count);
  cout << "\n  screen depths available: ";
#ifdef OLD_PENTIUM
  for(i=0; i<depth_count; i++) {
#else
  for(int i=0; i<depth_count; i++) {
#endif
   cout << depths[i] << " ";
  }
  XFree(depths);
  cout << "\n  default visual: " << visual_class[default_visual] << ", depth " <<
    G.visual_depth << endl;

  
  window_fit(base_frame);

  Window temp_window = (Window)xv_get(base_frame, XV_XID);
  colormap = DefaultColormap(display,screen);

  make_std_cmaps();
  gc = DefaultGC(display, screen);

  return;
}



-- 
o============o  Sending unsolicited commercial e-mail (UCE)  to this address
 Legal Notice   is indication of your consent to pay me $120/hour for 1 hour
o============o  minimum for professional proofreading & technical assessment.
  Terrence Brannon * brannon@quake.usc.edu * http://quake.usc.edu/~brannon



This archive was generated by hypermail 2b29 : Tue Jan 04 2000 - 00:26:19 MET