Using back tick Markdown syntax for code span, prevents Markdown from processing embedded text. This is fine from Markdown point of view (i.e. create HTML examples and similar), it creates issues with appledoc as any Markdown link generated from known object, embedded inside back ticks isn't converted properly. To overcome this, we need to embed back tick inside description manually after parsing. In the same time we need to take only handle links we generate while leaving any user entered ones unchanged!
Tried this to see if Xcode3 would delimit next section with new line, but doesn't help. Will leave it as text for now - declaration formatting isn't preserved anyway.
This error was reported during indexing for any unknown HTML code symbol (for example `–`). Markdown processor converted plain chars into these symbols as part of the conversion and obviously docsetutil has some issues with it. The workaround was to use plain text for abstract when generating tokens files. This commit is partial fix, the following will also handle some cleaning up of the text to make it more suitable for display.
This was one of much requested features. It allows adding arbitrary files to generated documentation. It's enabled with one or more `--include` switches. All files and directories specified are simply copied to `docs` subfolder within generated HTML files. So basically, you're free to write any HTML or whatever you want included with the generated documentation. But the power lies in special "template" files. These are just normal text files which names end with `-template` (for example `document1-template.html). Extension of these files is not important - they will always be converted to .html! The files can reside on any subpath - the path will be preserved. All such files are processed using the same logic as any other comment, so you can use appledoc comment syntax, including cross referencing any object or member. You can also cross reference these files from "normal" comments (or other documents) by simply writing the filename without `-template` and extension. You don't have to deal with subpaths either, these will be automatically picked up for you! [Online documentation](http://tomaz.github.com/appledoc) is not yet updated, will do it shortly. At this point, it's basic stuff only. As such it has much potential for future (like adding markdown syntax for headings, images and similar - for now just use HTML tags). But at least it's a start and get's work done for the moment. Enjoy and let me know if you find something not working as expected :)
… special blocks. Closes #62. The issue was with comments like this one: /** Some text @warning Description */ - (void)method; Although all special blocks (warnings, bugs, examples and lists) are delimited with empty lines from preceding text, they are conceptually part of the same paragraph - they are converted to a paragraph item object and added to the same paragraph as preceding text. The reason for such handling is so that we can add such items to whatever paragraph - like @param or @return description etc. However when creating short description and tooltips for methods, the whole first paragraph (including all special blocks) was used. As from the users point of view, these are clearly delimited with empty line, the resulting documentation contained unexpected tooltips and short descriptions. These situations are properly handled now and only the text part of the first paragraph up to the first special block is used for short description and tooltip! Thanks to "BloodDragon" for pointing it out! *NOTE:* after implementing this part I noticed that special blocks were not rendered to the documentation in such cases if `--no-repeat-first-par` option was used. A bit more logic was required in such case, so appledoc now properly repeats omitted parts as a first paragraph of the description paragraphs of a comment! *IMPORTANT:* This commit requires updating template files!
…20. This feature was implemented by "BloodDragon"!
In Xcode 3.2.5 quick help window, declaration doesn't end the line, next item is simply drawn right after the declaration. Tried inserting <br /> and similar, but didn't help.
The problem was in doc set info.plist containing empty keys for unused values. Apparently Xcode requires keys not being present at all in such case. Haven't noticed this in documentation. Thanks to "BloodDragon" for pointing it out. Note that at this point only quick description and related API is shown, while parameters, declaration and the rest aren't - will need to look into that. IMPORTANT: template files need to be updated in order for this fix to work!
…iagnostics and support.
…ersion was used for generation.
This allows writting stuff like <br/> or <tt>something</tt> and be converted to HTML tags instead of being escaped by template engine. Note that escaped strings may still pop up in other places not covered by this commit. Perhaps it wouldn't hurt to simply use unescaped strings all the time? It should even make template engine operations faster as it wouldn't run escaping all the time.
… Closes #29. By default appledoc repeats first paragraph in members documentation. This can be optionally disabled with command line switch now.
…rom being hardcoded in source code to being changable within docset template structure itself. Doesn't change actual handling a bit though.
…ppledoc related information handling. Printing version makes it easier to diagnose problems in documentation generation related to specific versions or just determine if someone is using latest version.
…able for given class.
At this stage, hierarchy file is generated but it only contains categories and protocols.
Instead of displaying all entries (.h and .m files for example), first the file from comment is tried. If no comment, or missing source file information, the first header file from the object's sourceInfos list is returned. If no header file is found, the first file from the list is returned. Finally if no source information is found, nil is returned.
This renders labels for elements with multiple values at the top of the row instead of the middle.
As we use <br /> for delimiter, we don't want to have it HTML escaped by mustache, so we need to specify that in the template.
…ited. Repeating single paragraph resulted in strange looking documentation.