3

Amigos, he estado buscando como es la forma correcta de documentar código pero todos los motores de búsqueda me arrojan generadores de documentación, realmente necesito documentar correctamente para otros programadores un codigo JS que tengo: por ejemplo.

    if (!Element.prototype.getCss || !window.getCss) {
        Element.prototype.getCss = function(hide) {
    //propDenied == 'none|align|animation|background|font|flood|flex|column|color|box|border|text|transform|transition|scroll|mask|margin|padding|max|min|list|fill|clip|grid|justify|stroke|outline|overflow|page|image|perspective|pointer|position|quotes|resize|ruby|stop|table|top|touch|vector|marker|backface|opacity|hyphens|float|empty|clear|content|counter|cursor|direction|filter|ime|isolation|letter|line|mix|object|order|height|visibility|white|width|word|writing';
    //valueDenied=='auto|none|top|inline|normal|""|rgb|padding|0%|0s|0px';
            let props = window.getComputedStyle(this);
            let propValueDenied = '""|^\-([a-z \-]+)$';
            if (!!hide) {
                if (/string/i.test(Object.prototype.toString.call(hide))) {
                    hide = hide.split(',');
                    hide.forEach(i => propValueDenied += `|${i.trim().toLowerCase()}`);
                } else if (/array/i.test(Object.prototype.toString.call(hide))) {
                    hide.forEach(i => propValueDenied += `|${i.trim().toLowerCase()}`);
                }
            }
            let result = {};
            let Getval = result.__proto__.getVal = function() {
                let val = String(this);
                if (/[px\\s%]+/.test(val)) {
                    if (/[\s]+/.test(val)) {
                        val = val.split(/\D+/).filter(Boolean);
                        val.forEach((v, i) => val.splice(i, 1, parseFloat(v)));
                    } else {
                        val = parseFloat(val.replace(/[px\\s%]+/, ''));
                    }
                }
                return val;
            }
            for (let i of props) {
                let propName = i;
                let propValue = props.getPropertyValue(propName);
                let cond1 = !RegExp(`${propValueDenied}`, 'i').test(propName);
                let cond2 = !RegExp(`${propValueDenied}`, 'i').test(propValue);
                if (cond1 && cond2) {
                    result[propName] = propValue;
                    result[propName].getVal = Getval;
                }
            }!/dims/.test(propValueDenied) ? result.dims = this.getBoundingClientRect() : result;
            return result;
        }
    }

//ejemplo: document.querySelector('elemento').getCss().heigth -> "80px" (String)
//ejemplo: document.querySelector('elemento').getCss().heigth.getVal() -> 80 (integer)

Este es una función para obtener un objeto de todas las propiedades y valores css de un elemento del DOM, pero no sé como documentarlo de manera correcta sin llegar a ser "muy informal" por así decirlo.

¿Tienen algún tutorial o herramienta que pueda servir en este caso para Javascript?

Angel Zambrano
  • 612
  • 4
  • 13
  • 22
  • 1
    No estaria entendiendo.. a que te referis con documentar correctamente? si no queres un generador de documentacion, que estarias buscando? – gbianchi Aug 30 '18 at 23:44
  • documentar usando los @param y ese tipo de cosas, no se como se documenta o en que orden debe tener... – Angel Zambrano Aug 30 '18 at 23:51
  • Estaría buscando un tutorial, en caso de no tener uno de esos generadores de documentación – Angel Zambrano Aug 30 '18 at 23:53
  • Este no es el lugar ideal para pedir un tutorial. Esa clase de preguntas no son bien vistas en el sitio ya que no tienen una respuesta correcta. La mayoria de las documentaciones dependen de tu entorno de trabajo y de como se manejen... – gbianchi Aug 30 '18 at 23:56
  • ¿Cual es el sitio ideal para hacer ese tipo de preguntas si no recibo respuestas correctas aquí? – Angel Zambrano Aug 30 '18 at 23:59
  • 4
    No sabria decirte. Pero sos un usuario experimentado y sabes que las preguntas a las cuales no se les puede marcar una respuesta correcta se basan en opiniones y no cumplen con el formato correcto del sitio. Siempre podes preguntar estas cosas en el [chat] – gbianchi Aug 31 '18 at 00:00
  • @AngelZambrano a lo que te refieres con `documentar usando los @param y ese tipo de cosas, ` te lo hace el IDE, generalmente los de jetbrains, debes buscar el IDE que de adapte a tus necesidades en la web oficinal de ellos. – Albert Hidalgo Aug 31 '18 at 00:54
  • 2
    mepa que es una buena oportunidad para re formular la pregunta a "cómo documentar código javascript" incluir algunos ejemplos, responder con una comunity wiki que sirva de índice y que varios aportemos las formas automatizadas o manuales que mejores resultados dan. – alo Malbarez Aug 31 '18 at 03:02
  • 1
    Te puedes inspirar en alguna *Guía de estilo*, por ejemplo, [la de Google explica cómo documentar en su apartado 7](https://google.github.io/styleguide/jsguide.html#jsdoc). Esa es sólo una entre muchas. De hecho, [ya existe aquí una pregunta al respecto](https://es.stackoverflow.com/q/22406/29967), sería cuestión de decidirte por alguna *guía de estilo* y documentar siguiendo sus principios. Las *guías de estilo* orientan sobre un uso uniforme en el estilo de codificación, en el que los comentarios de código son sólo una parte de algo más amplio. Quizá convendría que profundices en ello. – A. Cedano Aug 31 '18 at 04:42
  • 1
    Si lo quieres ver resumido, [en mi respuesta a aquella pregunta](https://es.stackoverflow.com/a/59546/29967) he enumerado diez de las *Guías de estilo* Javascript más populares y por tanto más usadas. La respuesta provee el enlace a cada una de ellas. – A. Cedano Aug 31 '18 at 04:49
  • Amigos, para el interesado, encontré un plugin de Sublime Text3 que me agiliza y practimente me enseña como es la documentacion, el plugin se llama DocBlockr, soporta JavaScript (including ES6), PHP, ActionScript, Haxe, CoffeeScript, TypeScript, Java, Apex, Groovy, Objective C, C, C++ and Rust. Link: https://github.com/spadgos/sublime-jsdocs – Angel Zambrano Sep 01 '18 at 00:21

0 Answers0