Dartdoc: Требуется возможность создавать документы API на уровне библиотеки без явного тега библиотеки.

dartdoc получает от анализатора комментарий документа для всех элементов. Таким образом, анализатор необходимо будет модифицировать для поддержки получения комментариев к документации из файла dart перед первым объявлением.

@Sfshaza , не могли бы вы открыть

https://github.com/dart-lang/analyzer_cli/issues/81

После некоторого обсуждения новое предлагаемое правило проще:

Используйте первый комментарий документа, прикрепленный к любой директиве (импорт, экспорт и т. Д.).

Это исправление внесено в анализатор. Обновление до нового пакета анализатора, текущего 0.27.1 + 2, решит эту проблему.

Думаю, это поправят?

Не знаю, исправляли ли это когда-нибудь.

Я не вижу никаких библиотечных комментариев для документации stagehand, если я не добавлю оператор библиотеки ( library stagehand; ) над импортом. Мы удалили оператор library в https://github.com/dart-lang/stagehand/pull/307 (3/2016), v1.0.2, и именно тогда комментарии библиотеки исчезли из dartdoc: 1.0 .2 документы библиотеки , 1.0.1 документы библиотеки

Вы правы, нам по-прежнему требуется оператор библиотеки - если он был исправлен в какой-то момент, это было до того, как я взял его на себя.

И я вообще-то совсем не прав. К моему удивлению, это работает во внутренних тестах dartdoc. Не знаю, почему это не работает в вашем случае, потребуется некоторое расследование.

Очень странный. Спасибо, что изучили это. Пожалуйста, дайте мне знать, если я могу чем-нибудь помочь.

Есть обновления здесь?

Состояние AFAIK не изменилось.

Думаю, нам бы этого хотелось: https://github.com/dart-lang/language/issues/1073

@kevmoo Обратите внимание, что мы распознаем и генерируем документы для библиотеки, эта проблема связана с просьбой заметить блок комментария в начале файла без тега библиотеки и представить, что это комментарий документации библиотеки.

@kevmoo Обратите внимание, что мы распознаем и генерируем документы для библиотеки, эта проблема связана с просьбой заметить блок комментария в начале файла без тега библиотеки и представить, что это комментарий документации библиотеки.

Ага. Но я обнаружил, что многие люди не знают, как назвать свои библиотеки. Если бы он мог быть просто «голым», чтобы у нас было место, где можно было бы что-нибудь развесить - было бы неплохо.

Меньше догадок для таких вещей, как dartdoc и test

@kevmoo Предлагаемое решение в dart-lang / language # 1073 (иметь тег библиотеки без имени, например, library; ) - это способ, которым я бы предпочел решить эту проблему. Конечно, для меня это означает меньше работы, но, если серьезно, это гораздо менее «мягко» и подвержено сбоям с точки зрения случайного изменения комментариев в заголовке файла, чтобы нарушить хакерское сопоставление. Если есть данные, говорящие о том, что это большое влияние, мы или если у нас заблокированы критически важные пользователи и мы не можем дождаться языкового решения, мы перейдем на P1.

Если вы не включаете оператор библиотеки, тогда библиотека неявно именуется как имя файла, верно? Например, main.dart будет иметь неявное значение library main . Так почему же «пустой» оператор библиотеки не может сделать то же самое?

@ Levi-Lesches Нет особой причины, кроме того, что язык должен поддерживать наличие оператора library; без имени.

Да, я полностью согласен - это то, чего вы ожидаете от оператора library; ? Так же, как если бы его не было?

Да, я полностью согласен - это то, чего вы ожидаете от оператора library; ? Так же, как если бы его не было?

С моей точки зрения, он устраняет хитрости, которые у нас есть сейчас, чтобы разрешить «плавающие» аннотации - без необходимости думать о имени библиотеки.

@ Levi-Lesches В значительной степени. Единственное отличие состоит в том, что анализатор сможет подключать не только аннотации, но и документацию специально к этому оператору, и, следовательно, возвращать LibraryElement s для последующих потребителей инструментов, таких как dartdoc.

Объявление library; будет делать то же самое, что и объявление библиотеки, за исключением того, что вы можете повесить на него аннотации и dartdoc. Это объявление, представляющее саму библиотеку, например library foo.bar.baz; , но, в отличие от последнего, оно также не называет библиотеку.

Библиотека без объявления библиотеки имеет пустое имя, и library; также даст библиотеке пустое имя.