Есть ли некоторые хорошие и современные альтернативы Javadoc? [закрытый]
@Alexey: Если вы просто хотите узнать, как запустить твиттер из своего приложения, сделайте следующее:
NSURL *urlApp = [NSURL URLWithString: [NSString stringWithFormat:@"%@", @"twitter://"]];
if ([[UIApplication sharedApplication] canOpenURL:urlApp]){
[[UIApplication sharedApplication] openURL:urlApp];
}else{
UIAlertView *appMissingAlertView = [[UIAlertView alloc] initWithTitle:@"Twitter App Not Installed!" message:@"Please install the Twitter App on your iPhone." delegate:nil cancelButtonTitle:nil otherButtonTitles:@"Ok",nil];
[appMissingAlertView show];
[appMissingAlertView release];
}
10 ответов
Недавно я получил пересылку письма о том, что Sun работает над модернизацией вывода Javadoc HTML. Из указанного письма:
Мы предлагаем улучшения в javadoc / doclet для JDK7. В вики-страница проекта находится по адресу http://wikis.sun.com/display/Javadoc/Home . В рамках предложенного улучшений, пользовательский интерфейс вывода javadoc будет обновлен. Новый скриншоты дизайна загружаются в вики проекта. Вывод javadoc разметка будет изменена, чтобы она соответствовала действительному HTML и WCAG 2.0.
Так что определенно работа еще продолжается, даже если это несколько поздно. Однако, на мой взгляд, одним из самых больших недостатков Javadoc является его очень тесная связь с HTML. У многих классов есть документация Javadoc, которая включает буквальный HTML и также полагается на вывод в формате HTML. К сожалению, я думаю, это никогда не изменится. Тем не менее, это означает, что разработчики могут свободно включать в HTML все, что они хотят, который также может быть недействительным, неправильно сформированным и т. Д. Таким образом, адаптация вывода инструмента javadoc - это только одна часть этого, другая выиграла. t и не может измениться, и поэтому остается.
Что касается просмотра документации, я также считаю, что документация HTML немного громоздка. Обычно я использую представление Javadoc в Eclipse. У него тоже есть недостатки (медленно и можно
Лично я хотел бы, чтобы стандарт «документации комментариев» был более читабельным, чем HTML (и, следовательно, теговый) JavaDoc.
Например, MarkDown, используемый здесь, был бы отличным, читаемый человеком в источнике, красиво отформатированный вне источника.
В текущем JavaDoc, я полагаю, многие люди используют комментарии JavaDoc, но фактически не документируют в той степени, в какой они могли бы. Я уверен, что все просматривали онлайновый JavaDoc API, который не был задокументирован или почти не задокументирован и до сих пор труднее использовать, чем должен быть.
Этому не помогают программы переформатирования кода (например, в Eclipse или, может быть, при фиксации исходного кода), которые полностью уничтожают любую читаемую структуру, которую вы могли поместить в комментарий JavaDoc (например, список элементов), в один большой кусок текста,
Кто-нибудь знает, есть ли какие-либо планы по развитию Javadoc каким-то стандартизированным способом?
Соответствующий JSR (JSR 260), который определяет улучшения Javadoc, был отклонен из JDK 7 (пока). Обзор того, что было запланировано (с этого сайта ):
Обновите Javadoc, чтобы обеспечить более богатый набор тегов, чтобы обеспечить более структурированное представление документации Javadoc. Этот JSR охватывает: категоризацию методов и полей, семантический индекс классов и пакетов, отличие статических, фабричных, устаревших методов от обычных методов, различие средств доступа к свойствам, объединение и разделение информации на представления, встраивание примеров и распространенных вариантов использования, и многое другое.
Общие перспективы для JDK 7 довольно мрачные .
Я создал Markdown (java) Doclet , который будет принимать исходные комментарии в тексте в формате Markdown и создавать те же HTML-документы Javadocs.
Новый доклет также делает некоторые рестайлинг текста, но сгенерированный HTML на этом этапе не изменяется.
Это каким-то образом решает проблемы с комментариями HTML в java, которые, вероятно, являются самой большой проблемой удобства использования текущей документации Javadoc.
I don't think that the concepts of Javadoc are outdated. As far as i can see, these concepts are rooted years ago in a product named doxygen, which is still available for other languages (i.e. Objective-C where it is heavily used). Even this has it's predecessors - have a look at the programming environment used by Donald Knuth to create TeX (Literate programming).
Nevertheless it is a intriguing idea to have a single source for program code and documentation.
Besides of that, the presentation of the documentation can be customized to your special needs using a plug-in system supported by the JavaDoc tool. You might provide a plug-in (as we do) that publishes directly into a database which is directly accessible via web. Using collaborations anyone can provide additional comments or clarifications to the documentation that might find their way back into the original source.
Чтобы ответить на ваш практический вопрос, я погуглил, спросил друзей и придумал их. Forrestdoc, doclet и doxygen.
Второй вопрос, я бы сказал, что да, это не очень "Web-oh-twoeye", но, по крайней мере, вам гарантирована работа в автономной среде, и он достаточно мал, чтобы поставляться вместе с вашим API. Я не одобряю использование фреймов, но с javadoc это работает довольно хорошо. Планов по его замене не видел. Я не одобряю использование фреймов, но с javadoc это работает довольно хорошо. Планов по его замене не видел. Я не одобряю использование фреймов, но с javadoc это работает довольно хорошо. Планов по его замене не видел. Eclipse имеет некоторую поддержку javadoc в части его чтения, интерпретации и создания.
Лично я все еще считаю Javadoc очень полезным. Тем более что он стандартизирован. Я не знаю ни одного основного стиля документации, в котором мне было бы легче ориентироваться (это вполне может быть субъективным, но я лично считаю, что использование MSDN, например, ужасно).
Для поиска: используйте Javadoc Search Frame , он значительно упрощает использование Javadoc всех видов. Он доступен как пользовательский сценарий для Firefox и как расширение Google Chrome .
Вы можете сформулировать это менее агрессивно и властно. Большинство людей не заботится о том, как выглядит технический ресурс, и о том, что «Веб 2.0 недостаточно!» звучит как банальный маркетроид.
А что именно вы считаете «более удобным»? Лично мне определенно нужен полнотекстовый поиск и более удобный браузер, и AJAX, вероятно, может помочь в этом.
Что ж, хорошая вещь в JavaDoc заключается в том, что он противоположен устаревшему - он произвольно расширяемый. Почему бы вам не пойти дальше и не написать доклет , который производит тот тип документа API, который вам нужен?
Почему никто еще не сделал этого до сих пор (что, по-видимому, так), остается только догадываться - возможно, никто не думает об этом так сильно, как вы.
Есть доклет DocBook. DocBook - это более богатый тип документа, чем (X) HTML, и он лучше подходит для описания технического содержания. Из исходников DocBook вы можете создавать всевозможные форматы вывода.
Javadoc - лучшая система автоматической генерации документации исходного кода, которую я когда-либо видел. Во многом это связано с тем, что это так просто - я могу просматривать javadoc-файлы даже на моем 5-летнем мобильном телефоне, если я хочу! Хотя я согласен с тем, что небольшая подтяжка лица может быть в порядке, и особенно JDK - это боль для просмотра, я бы не осмелился полностью изобретать колесо, потому что в настоящее время у нас есть RESTful, простое в использовании решение для своей цели, которое работает почти где угодно.