Список @идентификаторов , TODO или что это такое?

#java #cpp #документация #комментарии

Я видел что в некоторых исходных кодах JS например JQuery комментируют так:

// Define a local copy of jQuery


но это просто строка для людей а

// TODO:


это уже обнаруживается большинством IDE но JS не типизированный язык поэтому спрашиваю
про другие например я видел в некоторых исходных кодах на Java (в основном помоему)
или C++ (какой код здесь и придумал) в комментариях вставляют описания определяемых
ф-ции и т.д. примерно (взял с потолка потому что не знаю что это такое и Java) так:

/*
 @function getSquare
 @args:
 @x int 
 @returns int
*/
int getSquare(int);
...
int getSquare(x){
  return x*x;
}


Что это вообще такое за @... все поисковики уже измучал не нашёл мне кажется что
есть и @TODO просто в JS @ можно опускать. Или @ это что то типа директивы препроцессора
в Java (типа # в c++) или это надо применять в документации а не в исходном коде? 
Сильно не пинайте я уже спрашивал  Научиться писать документацию и хорошо комментировать
код только про JS и только @lampa сказал 


  У вас что, на калькуляторе поиск сломался?


а @Котик:


  Ахаха


но это было про JS а этот вопрос про C++ Java etc. Вопрос к профессионалам объясните
что за @... и т.д и какие можно в исходном коде и документации использовать ключевые слова
    

Ответы

Ответ 1

Говоря простым языком, это называется самодокументированием кода в стиле JavaDoc.
Пример:
class Test {

   /**
    * Разделить одно число на другое
    * 
    * @param int x 
    * @param int y
    * @return int
    */
   public int divide(int x, int y)
   {
      return x/y;
   }
}

Где все, что начинается с "собачки" - называется тегами описания. Из примера:
Эти теги, они стандарты. Не нужно придумывать своих.
Самые основные:
Тег @param int x - означает какой параметер будет передам в функцию
Тег @return - означает какое возращаемое значение мы ожидаем
Тег @author - означает кто автор
Тег @copyright - Авторские права
Тег @license - Лицензия
Тег @version - Версия

итд их много, если нужны все в гугл: JavaDoc Style
JavaDoc Style используется не только в Java, но также и в C#/C/C++ и PHP для само-документирования
классов и методов. Некоторые используют даже в JavaScript.
Это нужно для того чтобы, облегчить чтение/понимание кода. Это общепринятый стандарт/правило
для документирования своего кода.


Ответ 2

Ну вот же, документирование кода Java. У Вас действительно поиск сломался?


Ответ 3

Почитайте про полузабытый API Java Taglet