2009-08-17 Robert Dewar <dewar@adacore.com>

[pf3gnuchains/gcc-fork.git] / gcc / ada / prj-pars.ads

diff --git a/gcc/ada/prj-pars.ads b/gcc/ada/prj-pars.ads
index 8c22ba4..01caff9 100644 (file)
--- a/gcc/ada/prj-pars.ads
+++ b/gcc/ada/prj-pars.ads
@@ -6,7 +6,7 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
---          Copyright (C) 2000-2007, Free Software Foundation, Inc.         --
+--          Copyright (C) 2000-2009, Free Software Foundation, Inc.         --
 --                                                                          --
 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
 -- terms of the  GNU General Public License as published  by the Free Soft- --
@@ -23,7 +23,7 @@
 --                                                                          --
 ------------------------------------------------------------------------------
 
---  Implements the parsing of project files
+--  General wrapper for the parsing of project files
 
 package Prj.Pars is
 
@@ -35,21 +35,25 @@ package Prj.Pars is
       Project           : out Project_Id;
       Project_File_Name : String;
       Packages_To_Check : String_List_Access := All_Packages;
-      When_No_Sources   : Error_Warning := Error;
+      Flags             : Processing_Flags;
       Reset_Tree        : Boolean := True);
-   --  Parse a project files and all its imported project files, in the
-   --  project tree In_Tree.
+   --  Parse and process a project files and all its imported project files, in
+   --  the project tree In_Tree.
+   --  All the project files are parsed (through Prj.Tree) to create a tree in
+   --  memory. That tree is then processed (through Prj.Proc) to create a
+   --  expanded representation of the tree based on the current scenario
+   --  variables. This function is only a convenient wrapper over other
+   --  services provided in the Prj.* package hierarchy.
    --
-   --  If parsing is successful, Project_Id is the project ID
-   --  of the main project file; otherwise, Project_Id is set
-   --  to No_Project.
+   --  If parsing is successful, Project is the project ID of the root project
+   --  file; otherwise, Project_Id is set to No_Project. Project_Node_Tree is
+   --  set to the tree (unprocessed) representation of the project file. This
+   --  tree is permanently correct, whereas Project will need to be recomputed
+   --  if the scenario variables change.
    --
    --  Packages_To_Check indicates the packages where any unknown attribute
-   --  produces an error. For other packages, an unknown attribute produces
-   --  a warning.
-   --
-   --  When_No_Sources indicates what should be done when no sources
-   --  are found in a project for a specified or implied language.
+   --  produces an error. For other packages, an unknown attribute produces a
+   --  warning.
    --
    --  When Reset_Tree is True, all the project data are removed from the
    --  project table before processing.