Справочная система

← →
Bartov (2002-12-02 10:23) [0]

Давно хотел затронуть этот вопрос по поводу справочной системы.
Из форума я вынес для себя одно, что многие не могут понять, как пользоваться компонентами, написанные разными авторами. Тем более некоторые авторы, вообще не пишут ни какой документации к своим творениям, а те, кто ими пользуются, не могут понять, что к чему и какие есть у компонента методы и свойства!

Для тех, кто пишет компоненты и модули:
1) Делайте help, чтоб xHelpGen мог создать ее.
2) Пишите код более читабельным, а то иногда посмотришь исходники, а там черт ногу сломает.
3) К компоненту должна прилагаться демка.
Пусть все это будет стандартом для создателей компонентов!!!

Для тех, кто пользуется ими:
Вообще-то давно существует программа xHelpGen, которая создает файл справки по всему KOL’у и дополнительным компонентам и модулям. Ее вы можете скачать с http://bonanzas.rinet.ru, надеюсь, что она появится и на kol.mastak.ru!!! Вам осталось запустить ее, и вы получите справку в HTML формате.

Я уже внедряю поддержку xHelpGen в свои компоненты. Так, что на этой недели ждите обновления.

Ну что скажите авторы и пользователи?!

← →
Bartov (2002-12-02 10:32) [1]

Загрузить xHelpGen можно от сюда http://bonanzas.rinet.ru/xhelpgen.zip

← →
Gandalf (2002-12-02 11:59) [2]

> 1) Делайте help, чтоб xHelpGen мог создать ее.

Грешен... исправлюсь, пока времени нет, но часть моих компонентов - конверты для коих есть настоящие хелпы и доки. Вообще мой девиз MCK=VCL-Stuff, то бишь компонент для KOLnMCK это полная копия VCL, а для VCL всегда есть хелп. Но это не оправдание, буду делать хелпы, причем и на русском тоже.

> 2) Пишите код более читабельным, а то иногда посмотришь
> исходники, а там черт ногу сломает.

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

> 3) К компоненту должна прилагаться демка

См. 1. Вообще-то демки есть, ведь и я должен где-то все это тестить, просто исторически (Кладов виноват, сказал: демки да лано, потом как нибуть выложим :) сложилось что я их не выкладываю. Ладно в следующей обновке обещаю Демки.

← →
Bartov (2002-12-02 16:35) [3]

2Gandalf

Я еще имел ввиду как оформлять сам файл и чтоб он был лекго читаемый:
http://www.econos.de/delphi/cs.html

Если тяжело самому превисти все впорядок, то вот ссылка на программку(для всех версий Делфи):
http://www.dow.wau.nl/aew/downloads/DelForEx.zip

← →
Bartov (2002-12-03 01:25) [4]

Народ, ну выскожите свое мнение!!!
Это ведь не для нас с Gandalf"ом только надо. Мы ведь и ваше мнение слушаем!

← →
blackalex © (2002-12-03 10:35) [5]

Я как пользователь могу только дополнить Бартова.

1) Кладов придумал довольно простой и интересный метод создания документатии. Создатели компонентов могли бы его взять за основу и использовать при написании своего кода. Коментарии к коду на мой взгляд никогда не лищние. Иногда 2-3 слова вполне хватает , чтобы кратко описать что делает та или иная функтия. А также коментарии или хелп писать лучше на английском, так как русский (windows-1251) нечитабелен на английских и других системах.

2) Вопрос спорный. Каждый программист пишет так как ему нравиться. Но, к примеру на нашей фирме, существиют определенные правила написания кода. Так у нас писать не разрешаеться:
if then
begin
код
end
else
begin
код
end

а надо так:

if условие then begin
код
end
else begin
код
end

Правда мне было бы все равно, но если честно, то второй вариант мне симпатичнее и я его нахожу болле читабельным чем первый.

3) я тоже за демку обеими руками. Это как маленький туториал. Намного прощее разбираться в коде, при этом экономиться время.

← →
Bartov (2002-12-03 13:45) [6]

Ура! Уже есть первое мнение.

>Создатели компонентов могли бы его взять за основу и использовать при написании своего кода. Коментарии к коду на мой взгляд никогда не лищние. Иногда 2-3 слова вполне хватает , чтобы кратко описать что делает та или иная функтия.

Я про все это и говроил. ;-)

>Каждый программист пишет так как ему нравиться.

Ну извените, вот такой код:
if x < 0 then begin ... z := 2; end;
Это... просто слов нет...

>Правда мне было бы все равно, но если честно, то второй вариант мне симпатичнее и я его нахожу болле читабельным чем первый.

Да, можно еще и так:
1. if ... tnen begin ... end else begin ... end;

2. if ... then else ...

Но так нагляднее: if ... then x := 1 else x := 2;

← →
Arioch (2002-12-03 15:02) [7]

Ну разрешать-запрещать IMHO перебор, но вот лично мне (у меня часто бываютя длинные списки IF"ов, когда в case не влазит :-) ) симпатичнее 2-1 вариант с 1 поправкой:

end else begin

потому что если идет цепочка, то получается

if XXXX then begin
YYY
ZZZ
end else if XXXXX then begin
YYYYY
и т.д.

Кстати, а никто не хотел бы покопаться в xHelpGen"e и сделать вывод в hlp ? :-)

← →
blackalex © (2002-12-03 17:19) [8]

> Кстати, а никто не хотел бы покопаться в xHelpGen"e и сделать вывод в hlp ? :-)

Для этого необходим еще Help Workshop от Microsoft, чтобы hlp компилить. Раз xHelpGen генерируйет html файлы, то тогда проще бы было зделать chm. Опять же для этого нужен компилятор - HTML Help Workshop

Что мне в xHelpGen"е не нравиться , то он создает html файлы в той же папке, где лежат и pas исходники. Выло бы классно параметрами ему указывать где лежат pas исходники и куда ему html файлы копировать . Типа

xHelpGen <PAS-Dir> <HTML-Dir>

← →
Arioch (2002-12-03 17:32) [9]

По поводу папок - согласен.
А что до Help WorrkShop - то вроде он в поставке то ли Delphi то ли Builder"a был.

← →
Bartov (2002-12-03 20:00) [10]

2blackalex
>Что мне в xHelpGen"е не нравиться , то он создает html файлы в той же папке, где лежат и pas исходники.

Все можно настроить!
xHelpGen.exe создает файл xHelpGen.ini
Вот и ваши настройки с каталогами, подправти их перезапустите его.
[Source] SourcePath=C:\Program Files\Borland\KOL\ ResultPath=C:\Program Files\Borland\KOL\
Читать лучше надо! Кладов писал об этом в тектовиках.
Хочу к xHelpGen утилитку написать ;-)

← →
Arioch (2002-12-04 00:28) [11]

Delphi 5 Enterprise: d:\Borland\Delphi5\....

KOL: d:\borland\AddOns\KOL

xHelpGen 1: d:\borland\AddOns\KOL
[Source]
SourcePath=.\
ResultPath=.\

Работает.

xHelpGen 2: d:\borland\AddOns\KOL\Help
[Source]
SourcePath=..\
ResultPath=..\

Работает.

xHelpGen 3: d:\borland\AddOns\KOL\Help
[Source]
SourcePath=..\
ResultPath=.\

НЕ работает.

Что я еще могу прочитать лучше?

Все можно настроить!
xHelpGen.exe создает файл xHelpGen.ini
Вот и ваши настройки с каталогами, подправти их перезапустите его.

[Source]
SourcePath=C:\Program Files\Borland\KOL\
ResultPath=C:\Program Files\Borland\KOL\

И то правда! А я чёто и ни туды. Покорнейше благодарю

← →
Vladimir Kladov (2002-12-06 09:37) [13]

Указывайте абсолютный путь.

Справочная система – для ВСЕХ! Найти похожие ветки