Правильно ли писать в README.md описания методов?

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

Есть README.md. Как лучше оформить описание методов? Мне кажется, что сейчас неправильно.


  VerticalHorizontalScrollView
  
  I did not find the ScrollView with two scrolls and decided to write it myself :D
I present VerticalHorizontalScrollView - ScrollView with both scroll directions and
little customization!
  
  scrollTo (int x, int y)
  
  Scroll container to X and Y axis without smooth animation
  
  smoothScrollTo (int x, int y)
  
  Scroll container to X and Y axis with smooth animation and default speed
  
  smoothScrollTo (int x, int y, int speed)
  
  Scroll container to X and Y axis with smooth animation and animation duration (ms)
  
  setOnScrollListener (OnScrollListener listener)
  
  Set listener for scroll action
  
  OnScrollListener.onScroll (int x, int y)
  
  Current X and Y axis scroll position

    

Ответы

Ответ 1

Описание методов

Вы вообще не должны документировать методы и классы в readme.

Для этой задачи существуют javadoc-комментарии в коде. Такие комментарии в том числе
показываются в среде разработки, что гораздо удобнее, чем заглядывать в ридми.

Даже дублировать комментарии из кода в ридми вручную не нужно, потому что вы создадите
себе лишнюю работу и неизбежно будете обновлять эти комментарии с задержкой.

Как ещё можно и нужно улучить эти комментарии:


Опишите принимаемые параметры с помощью @param x ...
Опишите возвращаемое значение с помощью @return ...
Опишите предусловия метода, когда они важны: когда можно вызывать метод, когда нельзя,
что необходимо сделать перед этим. Например, что будет, если вызвать smoothScroll в
то время, как ещё не закончился другой smoothScroll?
Опишите постусловия метода: что получится в результате. 


Пример:

/**
 * Scroll container to X and Y axis without smooth animation
 * 
 * @param x horizontal coordinate, [0..screen width]
 * @param y vertical coordinate, [0..screen height]
 */
public void scrollTo(
        final int x,
        final int y) {
    // code here
}


Создаём документацию из кода

В Java есть стандартный инструмент — Javadoc. Он может создавать статические веб-страницы
с документацией по коду Java. Эти страницы вы можете деплоить на GitHub Pages вручную
или с помощью сервера непрерывной интеграции. Можете использовать облачный сервер Travis,
он бесплатен для opensource-проектов.

Что делать с Readme?

Там должны быть совсем другие вещи: описание проекта, лицензия, инструкция по тому,
как добавить библиотеку в свой проект. 

Подробнее: Как написать хороший README?

Пара советов по code-style для markdown


Ставьте пустую строку после заголовков
Объединяйте тематические блоки под одним заголовком и внутри него используйте заголовки
на уровень ниже:

# Methods

## scrollTo

## smoothScrollTo

# License

Каждое предложение в абзаце начинайте с новой строки.
Можно ещё больше дробить предложения, желательно так, чтобы длина строки была не
больше сотни символов.


Ответ 2

Method name

 // description

 { codeblock }


Мне кажется будет самое то, если ещё подключить HighlighterJS или ему подобные.

Ещё вариант

# Global Method
## Method1
//description
{ codeblock } 
## Method2