PutDescription and non-static members

[Pedro Gea]

Aunque el mecanismo propuesto para poner una descripción a los miembros de una clase es mediante atributos del tipo: "_.autodoc.member.[MemberName]". Éste es insuficiente si se desean localizar (traducir o adaptar a un lugar) estas clases y sustituir estas descripciones según el idioma seleccionado.

Al intentar implementar unos mecanismos para cambiar la descripción de los miembros una vez ya creada la clase, nos encontramos que no hay manera de cambiar estas descripciones sin tener una instancia de dicha clase, ya que @Clase::Member no es accesible salvo para miembros estáticos.

Si pensamos en paquetes, el objetivo es poder crear un único paquete, independiente de la lengua seleccionada, y cambiar las descripciones a posteriori, en el StartActions.

Bastaría con una función del tipo: ClassPutDescription(Text description, Text classMember).

También me pregunto si una clase admite descripción. En ese caso, quizá podría extenderse la función propuesta para que acepte el nombre de la clase: ClassPutDescription(description, className)

Podría implementarse también una función del tipo: ClassDescription(Text classMember) complementaria a la anterior, que permita obtener la descripción de un miembro de una clase o de la propia clase si fuera el caso.

[Víctor de Buen Remiro]

La función PutDescription hace tiempo que es capaz de hacer eso, desde el ticket #604 concretamente:

Anything PutDescription(Text nuevaDescripción, Anything objeto)

Pone una nueva descripción a un objeto. Es posible modificar la descripción de un Struct o un Class pasándo el nombre de la misma entre comillas dobles

Ejemplo de uso:

Class @Ejemplo {
  Real _.valor
};

Anything PutDescription("Clase de ejemplo","@Ejemplo");

Lo que falta es que la función Description pueda hacer lo mismo o algo similar. Igual no es posible tan sencillo puesto que PutDescription es una función especial que tiene acceso al árbol y sabe que le le han pasado un texto entre comillas, pero si no es posible hacerlo así se le puede meter un argumento opcional. Yo creo que es mucho mejor eso que tener funciones especiales.

[Víctor de Buen Remiro]

(In [3465]) Fixes #1178

[Pedro Gea]

Poner o no descripciones a las clases puede ser interesante, de hecho lo preguntaba en los dos últimos párrafos.

Ponerle la descripción a un miembro estático de la clase tampoco supone un problema:

Class @Ejemplo {
  Static Real static = 1;
  Real nonStatic
};
Anything PutDescription("Atributo estático", @Ejemplo::static);
Text Description(@Ejemplo::static);
//> "Atributo estático"

La pega está en ponérselo a un miembro no estático, ya que no son miembros de la clase sino de la instancia y no están accesibles:

//? Anything PutDescription("Atributo no estático", @Ejemplo::nonStatic);
@Ejemplo ejemplo = [[ Real nonStatic = 2 ]];
Text Description(ejemplo::nonStatic);
//> ""

La única forma que conozco es mediante la declaración de atributos Text _.autodoc.member.[Member] pero esto no permite cambiar las descripciones a posteriori.

[Víctor de Buen Remiro]

Ok, está claro. Ha sido un acto reflejo, al resolver parte del problema me olvido del resto y lo doy por cerrado. En los casos de tickets polifacéticos como éste no es raro que me pase.

[Víctor de Buen Remiro]

Andaba yo despistado con esto de la descripción de los miembros estáticos.
No hay ni ha habido nunca ningún problema pues se puede usar PutDesription sobre ellos igual que sobre cualquier otro objeto.

Class @A
{
  Static Real static_member = 3
};

Real PutDescription("Miembro estático de ejemplo",@A::static_member);

Text Description(@A::static_member);

[Víctor de Buen Remiro]

(In [3469]) Refs #1178

[Pedro Gea]

Siento insistir, el motivo original del tique (véase el título del tique) es poner descripción a miembros no estáticos y que yo sepa no se puede.

El cambio [3469] hace referencia a #1184 y no a éste.

[Víctor de Buen Remiro]

No me había dado cuenta de lo que pedías pero es que lo veo completamente absurdo y quizás por eso subconscientemente no leía lo que ponía porque no podía ser.

Los miembros de una clase no son objetos sino prototipos de objetos así que es imposible hacer nada con ellos, y tampoco veo que tenga ningún sentido hacerlo.

La descripción se pone en la clase con _.autodoc.member. que es como hay que ponerlo y no veo necesidad de poder cambiarla luego. Hay que ponerla en el código para que todo el mundo que la use pueda verla porque la clase es de toda la comunidad que la use.

Lo que sí puedes cambiar es la descripción de un miembro de una instancia porque ya es un objeto.

Class @A
{
  Real x;
  Static Real static_member = 3
};

@A a = [[ Real x=1 ]];

Real PutDescription("Miembro x de instancia de ejemplo",a::x);
Real PutDescription("Miembro estático de ejemplo",@A::static_member);

Text Description(@A::static_member);
Text Description(a::x);

[Víctor de Buen Remiro]

(In [3471]) Fixes #1178

[Víctor de Buen Remiro]

(In [3472]) Refs #1178

[Víctor de Buen Remiro]

A ver si ahora ya he dado en el clavo.
Se añade un tercer argumento opcional a PutDescription que debe ser el nombre de un miembro de la clase especificada en el segundo argumento. Da igual si es estático o no.

Class @A
{
  Text _.autodoc.member.x = "Descripción vieja de x";
  Real x=?;
  Text _.autodoc.member.f = "Descripción vieja de f";
  Real f(Real void) { ? };
  Text _.autodoc.member.static_member = "Descripción vieja de static_member";
  Static Real static_member = 3
};

@A a = [[ Real x=1 ]];

Text old.autodoc.x = @A::_.autodoc.member.x;
Text old.autodoc.f = @A::_.autodoc.member.f;
Text old.desc.x = Description(a::x);
Text old.desc.f = Description(a::f);


Real PutDescription("Clase de ejemplo","@A");
Real PutDescription("Descripción nueva de x","@A","x");
Real PutDescription("Descripción nueva de f","@A","f");

//Con los estáticos se puede hacer de las dos formas
Real PutDescription("Descripción nueva de static_member","@A","static_member");
Real PutDescription("Descripción nueva de static_member",@A::static_member);

Text new.autodoc.x = @A::_.autodoc.member.x;
Text new.autodoc.f = @A::_.autodoc.member.f;

@A b = [[ Real x=2 ]];

Text new.desc.x = Description(b::x);
Text new.desc.f = Description(b::f);

[Víctor de Buen Remiro]

Obsérvese que en el comentario anterior todos los miembros tenían su correspondiente _.autodoc.member que también es transformado por PutDescription para mantener la integridad referencial interna.

Si no existe _.autodoc.member el PutDescription sólo cambia la descripción de los métodos pero no de los objetos miembro ya que no existen en ninguna parte y no es posible cambiar algo que no existe. Si se quiere cambiar la descripción de un objeto miembro es necesario declarar su correspondiente _.autodoc.member. De lo contrario sólo se podría cambiar la descripción de las instancias una vez creadas.

Class @A
{
  Real x=?;
  Real f(Real void) { ? };
  Static Real static_member = 3
};

@A a = [[ Real x=1 ]];

Text old.desc.x = Description(a::x);
Text old.desc.f = Description(a::f);

Real PutDescription("Descripción nueva de x","@A","x");
Real PutDescription("Descripción nueva de f","@A","f");

@A b = [[ Real x=2 ]];

//Permanece sin descripción porque es un miembro sin _.autodoc.member
Text new.desc.x = Description(b::x);
//Sí tiene la descripción porque es un miembro aunque no tenga _.autodoc.member
Text new.desc.f = Description(b::f);

[Víctor de Buen Remiro]

En el último comentario debería poner

//Sí tiene la descripción porque es un MÉTODO aunque no tenga _.autodoc.member
Text new.desc.f = Description(b::f);

[Víctor de Buen Remiro]

(In [3581]) Refs #1178