Algunas ideas sobre enlaces a código fuente

Translations: en - Tags: documentation, librsvg

He estado actualizando la guía de manejo de texto en librsvg, en partes para describir cómo funciona el código — por ejemplo, cómo un elemento <text> se divide en un árbol de estructuras Chunk y Span.

Fíjate cómo esos enlaces van a la documentación interna de la biblioteca. En el HTML, rustdoc pone enlaces titulados "source" que te llevan al código fuente que corresponde a cada cosa.

Nota: Chunk tiene documentación, pero Span todavía no; aun no la he escrito. El poner los enlaces a la documentación interna me ayuda a ver qué cosas todavía no están documentadas. Tal vez una estructura struct Point { x: f64, y: f64 } no necesite mucha documentación pero algo complicado como Span sí que la requiere.

Otra forma de poner enlaces a esas cosas sería enlazar al código fuente de Chunk y Span. Esos enlaces van a la versión en HTML del código fuente que GitLab puede desplegar, para un commit en específico.

Por ejemplo, el enlace a Chunk va a https://gitlab.gnome.org/GNOME/librsvg/-/blob/4cd62ad9/src/text.rs#L48-66 y este URL se construye así:

  • gitlab.gnome.org - el servidor, obviamente
  • GNOME - nombre del grupo
  • librsvg - nombre del proyecto
  • blob/4cd62ad9 - prefijo del identificador del commit
  • src/text.rs#L48-66 - el archivo en el árbol de código fuente, más un identificador de fragmento para que GitLab pueda resaltar un rango de líneas.

Para obtener ese enlace, hay que menearle un poco:

  • Primero hay que irse a la página del proyecto. Navega hacia el archivo que quieres. (Consejo: aprieta t y comienza a escribir el nombre del archivo; te saldrá una lista de opciones.)

  • Si estás en la rama incorrecta, cámbiala hasta arriba de la página. Observa que el URL contiene algo así como .../blob/main/src/mi_archivo.txt

  • Aprieta el botón de Permalink cerca del principio de la página. Esto cambia el URL para que tenga el identificador del commit más reciente, i.e. blob/123abc/src/...

  • Ve a las líneas que quieres enlazar. Apriétale en el número de la primera línea, y luego Shift-click en la segunda línea. Esto cambia el URL para que tenga un rango de líneas en el identificador de fragmento, como #L12-34.

Eso lo hago cuando escribo descripciones que se refieren una revisión específica del código. Por supuesto, si el código cambia, la descripción tal vez tenga que actualizarse si se trata de documentación "permanente" — pero por lo menos nunca quedan enlaces rotos, o enlaces a código fuente que no concuerda con la descripción.

El primer método — enlazar a la documentación interna de la biblioteca — tiene la ventaja de que es documentación de deveras, con un sub-enlace al código fuente como un extra. Tal vez me gustaría que rustdoc generara enlaces al código fuente original en GitLab, pen vez de poner su propia copia del código fuente, pero no es de mucha importancia.

El segundo método, enlazar a una revisión específica en en la vista de código de GitLab, es un poco más directa cuando quieres que el lector vez el código fuente de manera inmediata. El lector tiene que leer el código fuente y no hay forma sencilla en GitLab de brincar a las definiciones de símbolos, por ejemplo, o de encontrar las implementaciones para los métodos de una struct. En cambio, lo que genera rustdoc sí tiene todo eso.

Por último, en conversaciones en tiempo real, puede ser que nada más ponga un enlace al blob/main de cualquiera que sea la revisión más nueva en ese momento. Asumo que mi interlocutor vaya a mirar el enlace inmediatamente, o muy ponto después de nuestra conversación, para que obtenga el mismo contexto que yo tenía en mente.

Supongo que cada método tiene su lugar:

  • Enlazar a la documentación generada a partir del código fuente — Es amigable para el lector al ofrecer más contexto; sirve bien para hacer exploración de alto nivel. Los enlaces pueden volverse obsoletos si le cambias de nombre a los símbolos, pues no guardamos la documentación ya generada para todas las revisiones.

  • Enlazar a blob/123abc o una revisión en particular — sin ambigüedades, bueno para enlazar al estado del código en algún punto en el tiempo, y el lector puede cortar y pegar el identificador del commit fácilmente a la línea de comandos de git o a cualquier otra herramienta.

  • Enlazar a blob/main o a revisión más reciente de una rama — fácil de hacer; sólo requiere menearle a GitLab para encontrar los números de línea. Sirve para conversaciones informales. Los enlaces pueden permanecer vigentes por mucho tiempo en documentación "permanente" si describes el código sólo de forma muy general y éste no cambia muy a menudo.