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

Есть 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

Ответ

Описание методов
Вы вообще не должны документировать методы и классы в 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 Каждое предложение в абзаце начинайте с новой строки. Можно ещё больше дробить предложения, желательно так, чтобы длина строки была не больше сотни символов.