Trabajando con la documentación de Android

Cuando empezamos a trabajar con las distintas clases en Android es común que se nos ocurra que alguna funcionalidad quedaría muy bien en la aplicación pero a veces por falta de experiencia y porque estamos empezando con el desarrollo en esta plataforma desconocemos los métodos y propiedades de cada clase lo cuál puede limitarnos si no sabemos dónde consultar esta información.

El equipo de desarrolladores de Android se preocupó por poner a nuestra disposición la información de referencia de los paquetes y clases que podemos utilizar en nuestras aplicaciones desde el sitio oficial de Android Developers.

Antes de empezar a conocer la distribución de la API de Android, debemos tener en claro que es una API.

Una Api es un conjunto de reglas para escribir funciones o hacer llamados a subrutinas y acceder a otras funciones en una librería.

Generalmente las API’s las podemos consultar desde un sitio web y nos hará una recopilación de errores, funciones, definiciones y muchas cosas útiles para entender cómo es que funciona alguna plataforma de desarrollo.

En este link puedes ampliar este tema.

Estructura de la documentación

Cuando nos encontremos en el sitio esta es la estructura que veremos:

• En el panel izquierdo encontraremos en la parte superior, el listado de los paquetes Android y Java que podemos utilizar en nuestras aplicaciones.
• En la parte inferior de este panel se encuentra el árbol de navegación de las clases que nos muestra el conjunto de clases e interfaces dentro del paquete que seleccionamos en el listado de paquetes.
• Y en el panel principal se desplegará toda la información de detalle de la clase o interfaz que hayamos seleccionado en el árbol de navegación.

Si por ejemplo nos vamos al paquete android.widget, en el árbol de navegación podremos ver todas las interfaces que corresponden  a los listeners que manejan los eventos de los elementos de la GUI  y las clases que son todos los elementos de la GUI que podemos incluir en las aplicaciones.

Encabezado de las clases

Una vez que hemos seleccionado la clase que nos interesa inspeccionar, veremos en el panel principal toda la información correspondiente. Vamos por partes.

En el encabezado de la clase veremos los siguientes elementos:

1. El nombre de la clase indicando si se trata de una clase o interfaz.
2. El árbol de herencia nos sirve para conocer las clases de las que podemos utilizar métodos o atributos y nos provee de los links directos hacia el detalle de cada una de ellas.
3. Las subclases directas e indirectas nos sirven para conocer si podemos trabajar con clases que tal vez sean más específicas de alguna función de la que requiera la aplicación. Podemos incluso optar por ocupar alguna de ellas en lugar de la clase que nos interesaba.
4. El menú de navegación contiene los links para que podamos saltarnos a secciones específicas de la documentación de la clase. Entre ellos tenemos los atributos XML heredados y con los que es válido trabajar en los layouts, la lista de métodos que podemos utilizar desde el código Java, etc. En un momento más detallaremos el contenido de cada uno de estos apartados.

Vistazo rápido de las clases

En este apartado veremos algunos links útiles como son:

• En algunos casos la misma documentación de Android Developers tendrá algún tutorial o artículo técnico que podemos visitar para ver el uso de la clase en cuestión.
• También, en esta parte, la documentación nos agrega los links directos hacia el detalle de los atributos XML que podemos utilizar, desde las clases padre de las que hereda la clase seleccionada hasta los propios de la clase.

Atributos XML

La parte principal de la documentación se encuentra en las tablas de resumen que tiene cada clase de la API. La primera tabla corresponde a los atributos XML que son válidos para crear el aspecto visual del elemento.

En esta tabla se enumeran las clases padre y la clase en cuestión para que identifiquemos los atributos que utilizamos y que se heredan de la otra clase y que aún así son válidos en el elemento actual.

Si expandimos la tabla (dando clic sobre el triángulo negro de la izquierda) veremos lo siguiente:

• El nombre del atributo tal y como se escribe en el archivo XML, ejemplo:android:autoText.
• Si estamos manipulando las interfaces directamente en el código Java, a veces nos preguntaremos cómo definir tal o cuál atributo al elemento, pues bien, la segunda columna corresponde al método en Java equivalente al atributo en XML de la izquierda. Muy útil ¿no?
• La tercera columna corresponde a la descripción del atributo, el aspecto visual o funcional que desencadenará el uso del atributo en el elemento de la aplicación.

Atributos Java heredados

La segunda tabla nos presenta los atributos que hereda la clase, los encontraremos de varios tipos y nos sirven para consultar o asignar valores muy específicos a los elementos con los que trabajamos. Esta parte tiene mucho que ver con Java, por lo que te recomiendo consultes los tipos de atributos de este lenguaje para que tengas más clara la idea.

• La primera columna nos indicará el tipo de atributo y los modificadores de acceso del mismo.
• La segunda columna contiene el nombre del atributo.
• La tercera columna contiene la descripción del atributo, es decir, el tipo de característica que define en el elemento.

Constructores

Esta tabla nos enlista los diferentes constructores por medio de los cuáles podemos crear una instancia de la clase en nuestra aplicación. Te invito a visitar este link para ampliar el aprendizaje de qué son y para qué sirven los constructores en Java.

La parte interesante de esta tabla reside en que si los constructores reciben como parámetros otras clases, nos coloca el link para que veamos el detalle de esas clases.

Métodos de la clase

Después nos topamos las tablas que contienen la lista de métodos públicos, protegidos (en caso de haberlos) y con otro tipo de modificador de acceso que son propios de la clase.

• En la primera columna se nos indicará el valor de retorno del método, lo cuál es útil cuando invocamos las funciones desde las aplicaciones.
• En la segunda columna encontraremos el nombre del método tal y como se escribe en el código Java, indicando los argumentos que debe recibir para que su llamado no genere error de compilación y una breve descripción de lo que hace.

Métodos heredados

Por último nos encontraremos con los métodos de las clases padre de las que hereda (en caso de que aplique). Como ves, se nos enlistan todas las clases padre con la opción de expandir la información que sigue el mismo formato que el de la tabla anterior.

Con esto terminamos, si te das cuenta la información está muy bien ordenada y nos brinda varios datos que nos facilitan la manipulación y conocimiento de los elementos con los que trabajamos en nuestras aplicaciones Android. Ahora que ya sabes la razón de ser de la documentación utilízala para ahorrarte tiempo (y quebradera de cabeza) a la hora de buscar el detalle de alguna clase, atributo y función.