Ticket #1220: descriptions.tol

//////////////////////////////////////////////////////////////////////////////
// Tipos de objetos con descripción:

NameBlock modulo = [[
  Real variable1 = 1;
  Real _.variable2 = 1;
  Real _variable3 = 1;
  Real funcion1(Real void) { ? };
  Real _.funcion2(Real void) { ? };
  Real _funcion3(Real void) { ? };
  Class @clase {
      Text _.autodoc.member.atributo1 = "";
    Real atributo1;
    Real _.atributo2;
    Real _atributo3;
      Text _.autodoc.member.metodo1 = "";
    Real metodo1(Real void) { ? };
    Real _.metodo2(Real void) { ? };
    Real _metodo3(Real void) { ? };
      Text _.autodoc.member.atributoClase1 = "";
    Static Real atributoClase1 = 0;
    Static Real _.atributoClase2 = 0;
    Static Real _atributoClase3 = 0;
    Static Real metodoClase1(Real void) { ? };
    Static Real _.metodoClase2(Real void) { ? };
      Text _.autodoc.member._metodoClase3 = "";
    Static Real _metodoClase3(Real void) { ? }
  };
  Struct @estructura {
    Real elemento
  };
  @clase instancia = [[
    Real atributo1 = 2;
    Real _.atributo2 = 3;
    Real _atributo3 = 1
  ]];
  Set conjunto = @estructura(1)
]];

//////////////////////////////////////////////////////////////////////////////

Anything PutDescription("Variable 1", modulo::variable1);
Anything PutDescription("Variable 2", modulo::_.variable2);
//! Anything PutDescription("Variable 3", modulo::_variable3);
Anything PutDescription("Función 1", modulo::funcion1);
Anything PutDescription("Función 2", modulo::_.funcion2);
//! Anything PutDescription("Función 3", modulo::_funcion3);

Anything PutDescription("La clase", "modulo::@clase");
Anything PutDescription("Atributo 1", "modulo::@clase", "atributo1");
Anything PutDescription("Atributo 2", "modulo::@clase", "_.atributo2");
Anything PutDescription("Atributo 3", "modulo::@clase", "_atributo3");
Anything PutDescription("Método 1", "modulo::@clase", "metodo1");
Anything PutDescription("Método 2", "modulo::@clase", "_.metodo2");
Anything PutDescription("Método 3", "modulo::@clase", "_metodo3");
Anything PutDescription("Atributo de clase 1", "modulo::@clase", "atributoClase1");
Anything PutDescription("Atributo de clase 2", "modulo::@clase", "_.atributoClase2");
Anything PutDescription("Atributo de clase 3", "modulo::@clase", "_atributoClase3");
Anything PutDescription("Método de clase 1", "modulo::@clase", "metodoClase1");
Anything PutDescription("Método de clase 2", "modulo::@clase", "_.metodoClase2");
Anything PutDescription("Método de clase 3", "modulo::@clase", "_metodoClase3");

Anything PutDescription("La estructura", "modulo::@estructura");
//! Anything PutDescription("Elemento", "modulo::@estructura", "elemento");

Anything PutDescription("La instancia", modulo::instancia);
Anything PutDescription("El conjunto", modulo::conjunto);

//////////////////////////////////////////////////////////////////////////////

Set Members(modulo);
Set ClassMembers("modulo::@clase"); //! Sólo encuentra descripciones autodoc
Set Members(modulo::instancia); //! No encuentra descripciones

Text Description(modulo::variable1);
Text Description(modulo::_.variable2);
//! Text Description(modulo::_variable3);
Text Description(modulo::funcion1);
Text Description(modulo::_.funcion2);
//! Text Description(modulo::_funcion3);

Text Description("modulo::@clase"); //! => Atributo 3
Set [[ //! NADA
  Text Description("modulo::@clase::atributo1");
  Text Description("modulo::@clase::_.atributo2");
  Text Description("modulo::@clase::_atributo3");
  Text Description("modulo::@clase::metodo1");
  Text Description("modulo::@clase::_.metodo2");
  Text Description("modulo::@clase::_metodo3");
  Text Description("modulo::@clase::atributoClase1");
  Text Description("modulo::@clase::_.atributoClase2");
  Text Description("modulo::@clase::_atributoClase3");
  Text Description("modulo::@clase::metodoClase1");
  Text Description("modulo::@clase::_.metodoClase2");
  Text Description("modulo::@clase::_metodoClase3")
]];

Text Description("modulo::@estructura");
//! Text Description("modulo::@estructura", "elemento");

Text Description(modulo::instancia);
Text Description(modulo::conjunto);

//////////////////////////////////////////////////////////////////////////////
// Problemas y dificultades
// 
// * La función PutDescription NO tiene un funcionamiento homogéneo.
//   Tiene dos funcionamientos:
//    * Sobre objetos (como PutName) pasados como argumento
//    * Sobre objetos pasando su nombre completo como argumento mediante un
//      texto entrecomillado. No vale usar una variable texto, pues como 
//      parece lógico, en ese caso sería ella la receptora de la descripción.
//   El primero funciona para objetos 'comunes' de TOL
//   El segundo está destinado para clases y estructuras. Está extendido
//   para miembros de una clase pasando su nombre como tercer argumento.
//   Esto presenta algunas limitaciones:
//    * No se puede usar el funcionamiento via nombres para objetos 'comunes'.
//    * No se puede usar cómodamente en un ciclo ya que no se pueden pasar
//      los nombres como argumento texto y hay que apañar un Eval.
//    * No se puede modificar la descripción de un miembro privado de un
//      nameblock (aunque sí de una clase).
//    * La función no devuelve nada.
//    * La función no advierte que poner una descripción al atributo
//      de una clase que no tiene _.autodoc.member no sirve de nada.
//      Bueno, sí, para cambiar la descripción de la clase por error.
// 
// * La función Description aún anda peor, pues presenta el doble 
//   funcionamiento, pero sin la extensión para miembros de clases.
//   De modo que debe buscarse otro mecanismo para acceder a esa información.
//  
// * La función Members permite acceder a la información de elementos de un
//   nameblock, incluido sus descripciones.
//   Accede sin dificultad a las descripciones de los miemebros de un 
//   nameblock 'común' pero no a las de una instancia.
//   Concretamente, al utilizar la función sobre una instancia se obtiene
//   información de sus atributos y sin descripciones.
// 
// * La función ClassMembers permite accecer a la información de miembros
//   de una clase incluyendo sus descripciones, pero sólo muestra 
//   descripciones de los miembros con _.autodoc.member (sea atributos o
//   métodos).

// Sugerencias:
//   
//  * En PutDescription aceptaría el funcionamiento vía texto, también para
//    objetos cualesquiera, de modo que funcionara:
//      Anything PutDescription("Variable 1", "modulo::variable1");
//      Anything PutDescription("Variable 3", "modulo::_variable3");
//    consiguiendo así poner descripciones también a elementos privados.
// 
//  * En Description añadiría la extensión del tercer argumento para 
//    miembros de una clase, equiparándola a PutDescription.
// 
//  * Buscaría alguna manera de forzar la declaración interna de los
//    _.autodoc.member de los atributos en una clase, y así evitar que el
//    PutDescription no tenga efecto.
//    Si no, en cualquier caso, solucionaría el bug que asigna la descripción
//    a la clase y quizá incorporaría una advertencia.
// 
//  * Intentaría que Members respondiera sobre una instancia devolviendo
//    también la información que como instancia hereda de la clase: las
//    descripciones de los atributos e información completa de métodos.
// 
//  * Solucionaría la limitación de ClassMembers a la hora de localizar las
//    descripciones de los miembros que no tienen _.autodoc.member sean 
//    atributos o métodos
// 
//////////////////////////////////////////////////////////////////////////////