From cd6246d0fc305bbe05c190122f5845837e5acb71 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Franti=C5=A1ek=20Dvo=C5=99=C3=A1k?= Date: Thu, 16 Dec 2004 14:04:34 +0000 Subject: [PATCH] API documetnation fixes. --- org.glite.lb.client-interface/interface/CountRef.h | 11 ++++ org.glite.lb.client-interface/interface/Event.h.T | 4 +- org.glite.lb.client-interface/interface/Job.h | 64 +++++++++++++++++++--- .../interface/LoggingExceptions.h | 4 +- .../interface/ServerConnection.h | 4 +- org.glite.lb.client-interface/interface/consumer.h | 19 +++++-- org.glite.lb.client-interface/interface/context.h | 32 +++++++++-- org.glite.lb.client-interface/interface/events.h.T | 7 ++- .../interface/jobstat.h.T | 1 - .../interface/notification.h | 2 +- .../interface/producer.h.T | 14 +++-- 11 files changed, 128 insertions(+), 34 deletions(-) diff --git a/org.glite.lb.client-interface/interface/CountRef.h b/org.glite.lb.client-interface/interface/CountRef.h index a8f61cf..2ade266 100644 --- a/org.glite.lb.client-interface/interface/CountRef.h +++ b/org.glite.lb.client-interface/interface/CountRef.h @@ -1,7 +1,18 @@ #ifndef __EDG_WORKLOAD_LOGGING_CLIENT_COUNTREF_HPP__ #define __EDG_WORKLOAD_LOGGING_CLIENT_COUNTREF_HPP__ +/** + * \define EWL_BEGIN_NAMESPACE + * + * Switching into glite.lb namespace (couple with EWL_END_NAMESPACE). + */ #define EWL_BEGIN_NAMESPACE namespace glite { namespace lb { + +/** + * \define EWL_END_NAMESPACE + * + * Leave the glite.lb namespace. + */ #define EWL_END_NAMESPACE } } EWL_BEGIN_NAMESPACE; diff --git a/org.glite.lb.client-interface/interface/Event.h.T b/org.glite.lb.client-interface/interface/Event.h.T index 64b4958..29834d3 100644 --- a/org.glite.lb.client-interface/interface/Event.h.T +++ b/org.glite.lb.client-interface/interface/Event.h.T @@ -23,7 +23,7 @@ #include "glite/lb/events.h" #include "glite/lb/notifid.h" -EWL_BEGIN_NAMESPACE; +EWL_BEGIN_NAMESPACE class Event { friend class Job; @@ -143,6 +143,6 @@ private: CountRef *flesh; }; -EWL_END_NAMESPACE; +EWL_END_NAMESPACE #endif diff --git a/org.glite.lb.client-interface/interface/Job.h b/org.glite.lb.client-interface/interface/Job.h index 8f69ed8..b13ce9b 100644 --- a/org.glite.lb.client-interface/interface/Job.h +++ b/org.glite.lb.client-interface/interface/Job.h @@ -15,12 +15,13 @@ * @version $Revision$ */ -EWL_BEGIN_NAMESPACE; +EWL_BEGIN_NAMESPACE /** L&B job. + * * Implementation of L&B job-specific calls. * Connection to the server is maintained transparently. -*/ + */ class Job { public: @@ -55,13 +56,60 @@ public: */ const std::pair queryListener(const std::string & name) const; - /** Manipulate LB parameters, the same as for edg_wll_Context in C */ - void setParam(edg_wll_ContextParam, int); - void setParam(edg_wll_ContextParam, const std::string); - void setParam(edg_wll_ContextParam, const struct timeval &); + /** + * Manipulate LB parameters. + * + * The same as for edg_wll_Context in C + * + * \param ctx INOUT context to work with + * \param val IN value + */ + void setParam(edg_wll_ContextParam ctx, int val); + /** + * Manipulate LB parameters. + * + * The same as for edg_wll_Context in C + * + * \param ctx INOUT context to work with + * \param val IN value + */ + void setParam(edg_wll_ContextParam ctx, const std::string val); + /** + * Manipulate LB parameters. + * + * The same as for edg_wll_Context in C + * + * \param ctx INOUT context to work with + * \param val IN value + */ + void setParam(edg_wll_ContextParam ctx, const struct timeval &val); - int getParamInt(edg_wll_ContextParam) const; + /** + * Get LB parameters. + * + * The same as for edg_wll_Context in C + * + * \param ctx INOUT context to work with + * \return integer value of the parameter + */ + int getParamInt(edg_wll_ContextParam ctx) const; + /** + * Get LB parameters. + * + * The same as for edg_wll_Context in C + * + * \param ctx INOUT context to work with + * \return string value of the parameter + */ std::string getParamString(edg_wll_ContextParam) const; + /** + * Get LB parameters. + * + * The same as for edg_wll_Context in C + * + * \param ctx INOUT context to work with + * \return timeval value of the parameter + */ struct timeval getParamTime(edg_wll_ContextParam) const; private: @@ -69,6 +117,6 @@ private: glite::wmsutils::jobid::JobId jobId; }; -EWL_END_NAMESPACE; +EWL_END_NAMESPACE #endif diff --git a/org.glite.lb.client-interface/interface/LoggingExceptions.h b/org.glite.lb.client-interface/interface/LoggingExceptions.h index 1d22a2e..15ce0ab 100644 --- a/org.glite.lb.client-interface/interface/LoggingExceptions.h +++ b/org.glite.lb.client-interface/interface/LoggingExceptions.h @@ -11,7 +11,7 @@ #include -EWL_BEGIN_NAMESPACE; +EWL_BEGIN_NAMESPACE class Exception: public glite::wmsutils::exception::Exception { public: @@ -139,6 +139,6 @@ public: -EWL_END_NAMESPACE; +EWL_END_NAMESPACE #endif diff --git a/org.glite.lb.client-interface/interface/ServerConnection.h b/org.glite.lb.client-interface/interface/ServerConnection.h index 333d0bd..eee3892 100644 --- a/org.glite.lb.client-interface/interface/ServerConnection.h +++ b/org.glite.lb.client-interface/interface/ServerConnection.h @@ -17,7 +17,7 @@ #include "glite/lb/JobStatus.h" #include "glite/lb/consumer.h" -EWL_BEGIN_NAMESPACE; +EWL_BEGIN_NAMESPACE /** Auxiliary class to hold an atomic query condition. */ class QueryRecord { @@ -301,6 +301,6 @@ private: edg_wll_Context context; }; -EWL_END_NAMESPACE; +EWL_END_NAMESPACE #endif diff --git a/org.glite.lb.client-interface/interface/consumer.h b/org.glite.lb.client-interface/interface/consumer.h index 5a8cf96..2f7ca29 100644 --- a/org.glite.lb.client-interface/interface/consumer.h +++ b/org.glite.lb.client-interface/interface/consumer.h @@ -2,7 +2,6 @@ #define __EDG_WORKLOAD_LOGGING_CLIENT_CONSUMER_H__ /*! - * \file client/consumer.h (lbapi.h originaly) * \brief L&B consumer API * * General rules: @@ -126,7 +125,7 @@ extern int set_server_name_and_port( /** * General query on events. - * Return events satysfying all conditions + * Return events satisfying all conditions * query records represent conditions in the form * \a attr \a op \a value eg. time > 87654321. * \see edg_wll_QueryRec @@ -231,6 +230,7 @@ int edg_wll_QueryJobsExtProxy( * \param jobid IN: query this job * \param flags IN: specifies optional status fields to retrieve, * \see EDG_WLL_STAT_CLASSADS, EDG_WLL_STAT_CHILDREN, EDG_WLL_STAT_CHILDSTAT + * \param status OUT: the status of the job */ int edg_wll_JobStatus( @@ -241,7 +241,12 @@ int edg_wll_JobStatus( ); /** - * Query LBProxy and use plain communication + * Query LBProxy and use plain communication. + * \param context IN: context to operate on + * \param jobid IN: query this job + * \param flags IN: specifies optional status fields to retrieve, + * \see EDG_WLL_STAT_CLASSADS, EDG_WLL_STAT_CHILDREN, EDG_WLL_STAT_CHILDSTAT + * \param status OUT: the status of the job */ int edg_wll_JobStatusProxy( edg_wll_Context context, @@ -341,7 +346,7 @@ int edg_wll_QueryListener( /** * Query LBProxy and use plain communication */ -int edg_wll_QueryListener( +int edg_wll_QueryListenerProxy( edg_wll_Context context, edg_wlc_JobId jobId, const char * name, @@ -375,9 +380,13 @@ void edg_wll_QueryRecFree(edg_wll_QueryRec *); /** - * default and maximal query timeout (in seconds) + * default query timeout (in seconds) */ #define EDG_WLL_QUERY_TIMEOUT_DEFAULT 120 + +/** + * maximal query timeout (in seconds) + */ #define EDG_WLL_QUERY_TIMEOUT_MAX 1800 #ifdef __cplusplus diff --git a/org.glite.lb.client-interface/interface/context.h b/org.glite.lb.client-interface/interface/context.h index 5f176d5..dd0fda4 100644 --- a/org.glite.lb.client-interface/interface/context.h +++ b/org.glite.lb.client-interface/interface/context.h @@ -2,7 +2,6 @@ #define _EDG_WORKLOAD_LOGGING_CLIENT_CONTEXT_H /** - * \file edg/workload/logging/client/context.h * \brief L&B API common context (publicly visible) and related definitions */ @@ -99,9 +98,32 @@ int edg_wll_SetParam( struct timeval; /* gcc, shut up! */ -int edg_wll_SetParamInt(edg_wll_Context,edg_wll_ContextParam,int); -int edg_wll_SetParamString(edg_wll_Context,edg_wll_ContextParam,const char *); -int edg_wll_SetParamTime(edg_wll_Context,edg_wll_ContextParam,const struct timeval *); +/** Set a context parameter of type int. + * \param ctx INOUT context to work with + * \param param IN parameter to set + * \param val IN value to set + * \retval 0 success + * \retval EINVAL param is not a valid parameter, or invalid value + */ +int edg_wll_SetParamInt(edg_wll_Context ctx, edg_wll_ContextParam param, int val); + +/** Set a context parameter of type string. + * \param context INOUT context to work with + * \param param IN parameter to set + * \param IN val to set (if NULL, default is used) + * \retval 0 success + * \retval EINVAL param is not a valid parameter, or invalid value + */ +int edg_wll_SetParamString(edg_wll_Context ctx,edg_wll_ContextParam param,const char *val); + +/** Set a context parameter of type timeval. + * \param INOUT ctx context to work with + * \param IN param parameter to set + * \param IN val value to set (if NULL, default is used) + * \retval 0 success + * \retval EINVAL param is not a valid parameter, or invalid value + */ +int edg_wll_SetParamTime(edg_wll_Context ctx,edg_wll_ContextParam param,const struct timeval *val); /** Get current parameter value. * \param context INOUT context to work with @@ -165,7 +187,7 @@ typedef enum _edg_wll_ErrorCode { int edg_wll_Error( edg_wll_Context context, char **errText, - char **eddDesc + char **errDesc ); /** Convert source code to printable string diff --git a/org.glite.lb.client-interface/interface/events.h.T b/org.glite.lb.client-interface/interface/events.h.T index e37be1f..8dbe498 100644 --- a/org.glite.lb.client-interface/interface/events.h.T +++ b/org.glite.lb.client-interface/interface/events.h.T @@ -2,7 +2,6 @@ #define __EDG_WORKLOAD_LOGGING_CLIENT_EVENTS_H__ /** - * \file edg/workload/logging/client/events.h * \brief contains definition of event type codes for use both by lbapi.h and dglog.h */ @@ -243,6 +242,10 @@ for ($event->getFieldsOrdered) { gen "\n"; @@@} +/** + * \typedef edg_wll_AnyEvent + * common structure definition contained in all types of the events + */ typedef struct _edg_wll_AnyEvent { _EDG_WLL_EVENT_COMMON } edg_wll_AnyEvent; @@ -314,7 +317,7 @@ extern edg_wll_Event *edg_wll_InitEvent(edg_wll_EventCode eventcode); /** * Free the contents of event structure - * \param IN event structure to be freed + * \param event IN structure to be freed * \warning As event structures are likely to be allocated in arrays, * the structure itself is not freed. * Its the responsibility of the caller to call free(event) diff --git a/org.glite.lb.client-interface/interface/jobstat.h.T b/org.glite.lb.client-interface/interface/jobstat.h.T index 129b61d..975bdc4 100644 --- a/org.glite.lb.client-interface/interface/jobstat.h.T +++ b/org.glite.lb.client-interface/interface/jobstat.h.T @@ -6,7 +6,6 @@ */ /*! - * \file client/jobstat.h * \brief edg_wll_JobStat definition and related stuff */ diff --git a/org.glite.lb.client-interface/interface/notification.h b/org.glite.lb.client-interface/interface/notification.h index a16215d..5c87c0f 100644 --- a/org.glite.lb.client-interface/interface/notification.h +++ b/org.glite.lb.client-interface/interface/notification.h @@ -129,7 +129,7 @@ int edg_wll_NotifReceive( /** Default socket descriptor where to select(2) for notifications. - * Even if nothing is available for reading freom the socket, + * Even if nothing is available for reading from the socket, * there may be some data cached so calling \see edg_wll_NotifReceive * may return notifications immediately. * diff --git a/org.glite.lb.client-interface/interface/producer.h.T b/org.glite.lb.client-interface/interface/producer.h.T index 188f25c..7b830b9 100644 --- a/org.glite.lb.client-interface/interface/producer.h.T +++ b/org.glite.lb.client-interface/interface/producer.h.T @@ -2,7 +2,6 @@ #define __EDG_WORKLOAD_LOGGING_CLIENT_PRODUCER_H__ /** - * \file edg/workload/logging/client/producer.h * \brief client API for storing data into L&B service */ @@ -349,6 +348,8 @@ extern int edg_wll_RegisterJobSync( * Partitionable jobs should set num_subjobs=0 initially, * and re-register when number of subjobs becomes known. * + * \param context INOUT context to work with + * \param job IN registered job * \param type IN EDG_WLL_JOB_SIMPLE, EDG_WLL_JOB_DAG, or EDG_WLL_JOB_PARTITIONABLE * \param user IN user credentials * \param jdl IN user-specified JDL @@ -427,13 +428,14 @@ enum edg_wll_UserIdType { /** * Change ACL for given job. - * \param specification of user's credential - * \param user_id_type type of user_id, + * \param context INOUT context to workt with + * \param user_id IN: specification of user's credential + * \param user_id_type IN type of user_id, * for EDG_WLL_USER_SUBJECT the user_id parameter is expected to be user's subject name * for EDG_WLL_USER_VOMS_GROUP the user_id is expected to be of the form VO:group specifying required group membersip as managed by VOMS - * \param permission ACL permission to change - * \param permission_type type of given permission (allow or deny operation) - * \param operation operation to perform with ACL (add or remove record) + * \param permission IN ACL permission to change + * \param permission_type IN type of given permission (allow or deny operation) + * \param operation IN operation to perform with ACL (add or remove record) */ extern int edg_wll_ChangeACL( -- 1.8.2.3