¿Qué es PHP Doc?

Resumen 100% real no feik
¿Qué es PHP Doc?

PHPDoc no es mas que un estandar informal que tenemos para documentar cédigo en PHP, de esta forma los editores de cédigo pueden mostrar sugerencias cuando implementemos el codigo que estamos comentando.

Es una adaptacion de Javadoc y, además de ayudar a los editores de código, también puede ser Util para algunos generadores de documentacion como phpDocumentor.

atajo para visual studio:

/*

una vez puesto los comentarios relacionados a los requerimientos de la funcion, al hacer un hover sobre la funcion nos mostrará la leyenda de esa misma documentacion donde sea que usemos esa función

Es una buena práctica documentar tus funciones y clases durante la realizacion del código.

Si cuando definís la función adelante de cada parámetro ponés su tipo, aparte de tiparlo fuertemente en el PhpDoc lo pone automáticamente

/**
 * @param int $n1
 * @param int $n2
 * @return int
 */
function suma(int $n1, int $n2): int {
    return $n1 + $n2;
}

Un saludo.
Con respecto a las buenas practicas de código, creo que hayun cambio ya. Ahora al poner en práctica el Clean Code, dice que, se debe documentar lo menos posible, que si se documenta algo, es porque es demasiado especial, pero, que no debemos tener documentación porque nuestro código debe ser tan limpio,que al leer la función, debemos saber que hace…

Va con clean code y principios SOLID.

Eso le ayuda mucho a la ide y a copilot entender lo que hacemos

jejejej llevo leyendo documentación y haciendo eso en todos los lenguajes que he programado algunos aceptan makdown
por ejemplo
/**

• hola soy un <h1>,

*/
muy bueno, existe una extension MINTLIFY que lo hace con un comando mas rapido…

Muy útil la documentación que nos podamos procurar para nuestro programador del futuro y para nuestro trabajo en equipo.

Mi aporte:

<?php 

/**
 * Esta función retorna la suma de dos números
 *
 * @param integer $n1
 * @param integer $n2
 * @return integer
 */
function suma(int $n1, int $n2){
    return $n1 + $n2; 
}

$resultado = suma(1,2); 


echo $resultado; 

Con las nuevas versiones de PHP 8+ nos podemos ahorrar ese trabajo, especificando los tipos de entrada de las funciones y el tipo de retorno. Usando nombres descriptivos se hace más facil dar entender lo que una función hace.

Para equipos de desarrollo con lo siguiente puedes agregar el autor y fecha en la que desarrollaste el metodo o la función.

“php-docblocker.functionTemplate”: {
“message”: {},
“extra”: {},
“param”: {},
“return”: {}
},
“php-docblocker.extra”: [
"@author Ing. Eminson Mendoza [email protected]",
"@since $CURRENT_DATE/$CURRENT_MONTH/$CURRENT_YEAR $CURRENT_HOUR:$CURRENT_MINUTE:$CURRENT_SECOND"
],

Buenisima la extención.

en lo particular haga algo similar peor no uso el param int y demás… y en mi documentalista suele poner un ejemplo de como usar los parámetros.

¿esta bien si lo hago de esta forma?

	//Esta función permite crear una carpeta
	//Recibe un parámetro 
	//Esta funcione es privada, y se utiliza en la función subir_archivos
	/*
	*
	*$nombre - nombre de la carpeta
	*
	* ejemplo $nombre = "carpeta"
	*
	* Devuelve true
	* 
	*/

pfff, lo vi en el curso de java pero que genial que se tenga en php 😮