Skip to content

Commit

Permalink
swiftMarkup Library
Browse files Browse the repository at this point in the history 
Replace ReST-flavored documentation comments with Markdown.

rdar://problem/20180412

In addition to full Markdown support, the following extensions are
supported. These appear as lists at the top level of the comment's
"document". All of these extensions are matched without regard to
case.

Parameter Outlines
------------------

- Parameters:
  - x: ...
  - y: ...

Separate Parameters
-------------------

- parameter x: ...
- parameter y: ...

- Note:
Parameter documentation may be broken up across the entire comment,
with a mix of parameter documentation kinds - they'll be consolidated
in the end.

Returns
-------

- returns: ...

The following extensions are also list items at the top level, which
will also appear in Xcode QuickHelp as first-class citizens:

- Attention: ...
- Author: ...
- Authors: ...
- Bug: ...
- Complexity: ...
- Copyright: ...
- Date: ...
- Experiment: ...
- Important: ...
- Invariant: ...
- Note: ...
- Postcondition: ...
- Precondition: ...
- Remark: ...
- Remarks: ...
- See: ...
- Since: ...
- Todo: ...
- Version: ...
- Warning: ...

These match most of the extra fields in Doxygen, plus a few more per request.

Other changes
-------------
- Remove use of rawHTML for all markup AST nodes except for those
not representable by the Xcode QuickHelp XSLT - <h>, <hr/>, and of
course inline/block HTML itself.

- Update the doc comment RNG schema to more accurately reflect Xcode
QuickHelp.

- Clean up cmark CMake configuration.

- Rename "FullComment" to "DocComment"

- Update the Swift Standard Documentation (in a follow-up commit)

- Update SourceKit for minor changes and link against cmark
  (in a follow-up commit).

Swift SVN r27727
  • Loading branch information
@bitjammer
bitjammer committed Apr 26, 2015
1 parent 9e28dc7 commit ca5876a
Show file tree
Hide file tree
Showing 48 changed files with 3,519 additions and 5,079 deletions.
2 changes: 0 additions & 2 deletions CMakeLists.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -259,8 +259,6 @@ endif()
set(LLVM_RUNTIME_OUTPUT_INTDIR "${LLVM_BINARY_DIR}")
set(LLVM_LIBRARY_OUTPUT_INTDIR "${LLVM_LIBRARY_DIR}")

set(CMARK_LIBRARY_OUTPUT_INTDIR "${CMARK_LIBRARY_DIR}")

set(SWIFT_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
set(SWIFT_BINARY_DIR "${CMAKE_CURRENT_BINARY_DIR}")

Expand Down
261 changes: 256 additions & 5 deletions bindings/xml/comment-xml-schema.rng
View file
Original file line number Diff line number Diff line change
Expand Up @@ -363,7 +363,194 @@
<define name="Discussion">
<element name="Discussion">
<zeroOrMore>
<ref name="TextBlockContent" />
<choice>
<ref name="BlockContent" />
<ref name="TextInlineContent" />
</choice>
</zeroOrMore>
</element>
</define>

<define name="List-Bullet">
<element name="List-Bullet">
<zeroOrMore>
<ref name="Item" />
</zeroOrMore>
</element>
</define>

<define name="List-Number">
<element name="List-Number">
<zeroOrMore>
<ref name="Item" />
</zeroOrMore>
</element>
</define>

<define name="Attention">
<element name="Attention">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Author">
<element name="Author">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Authors">
<element name="Authors">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Bug">
<element name="Bug">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Complexity">
<element name="Complexity">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Copyright">
<element name="Copyright">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Date">
<element name="Date">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Experiment">
<element name="Experiment">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Important">
<element name="Important">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Invariant">
<element name="Invariant">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Note">
<element name="Note">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Postcondition">
<element name="Postcondition">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Precondition">
<element name="Precondition">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Remark">
<element name="Remark">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Remarks">
<element name="Remarks">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="See">
<element name="See">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Since">
<element name="Since">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="TODO">
<element name="TODO">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Version">
<element name="Version">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Warning">
<element name="Warning">
<zeroOrMore>
<ref name="BlockContent"/>
</zeroOrMore>
</element>
</define>

<define name="Item">
<element name="Item">
<zeroOrMore>
<ref name="BlockContent" />
</zeroOrMore>
</element>
</define>
Expand Down Expand Up @@ -393,7 +580,7 @@
<!-- In general, template parameters with whitespace discussion
should not be emitted. Schema might be more strict here. -->
<element name="Discussion">
<ref name="TextBlockContent" />
<ref name="BlockContent" />
</element>
</element>
</oneOrMore>
Expand Down Expand Up @@ -435,7 +622,7 @@
should not be emitted, unless direction is explicitly specified.
Schema might be more strict here. -->
<element name="Discussion">
<ref name="TextBlockContent" />
<ref name="BlockContent" />
</element>
</element>
</oneOrMore>
Expand All @@ -445,7 +632,7 @@
<define name="Exceptions">
<element name="Exceptions">
<oneOrMore>
<ref name="TextBlockContent" />
<ref name="BlockContent" />
</oneOrMore>
</element>
</define>
Expand Down Expand Up @@ -506,11 +693,56 @@
<define name="ResultDiscussion">
<element name="ResultDiscussion">
<zeroOrMore>
<ref name="TextBlockContent" />
<ref name="BlockContent" />
</zeroOrMore>
</element>
</define>

<define name="BlockContent">
<choice>
<ref name="Attention"/>
<ref name="Author"/>
<ref name="Authors"/>
<ref name="Bug"/>
<ref name="Complexity"/>
<ref name="Copyright"/>
<ref name="Date"/>
<ref name="Experiment"/>
<ref name="Important"/>
<ref name="Invariant"/>
<ref name="Note"/>
<ref name="Postcondition"/>
<ref name="Precondition"/>
<ref name="Remark"/>
<ref name="Remarks"/>
<ref name="See"/>
<ref name="Since"/>
<ref name="TODO"/>
<ref name="Version"/>
<ref name="Warning"/>
<ref name="TextBlockContent"/>
<ref name="List-Bullet"/>
<ref name="List-Number"/>
<ref name="CodeListing"/>
</choice>
</define>

<define name="CodeListing">
<element name="CodeListing">
<zeroOrMore>
<ref name="zCodeLineNumbered"/>
</zeroOrMore>
</element>
</define>

<define name="zCodeLineNumbered">
<element name="zCodeLineNumbered">
<optional>
<data type="string" />
</optional>
</element>
</define>

<define name="TextBlockContent">
<choice>
<element name="Para">
Expand All @@ -521,8 +753,10 @@
<value>author</value>
<value>authors</value>
<value>bug</value>
<value>complexity</value>
<value>copyright</value>
<value>date</value>
<value>experiment</value>
<value>invariant</value>
<value>note</value>
<value>post</value>
Expand Down Expand Up @@ -579,6 +813,23 @@
<param name="pattern">.*\S.*</param>
</data>
</element>
<element name="emphasis">
<!-- Non-empty text content. -->
<data type="string">
<param name="pattern">.*\S.*</param>
</data>
</element>
<element name="Link">
<attribute name="href"/>
<data type="string">
<param name="pattern">.*\S.*</param>
</data>
</element>
<element name="codeVoice">
<data type="string">
<param name="pattern">.*\S.*</param>
</data>
</element>
<element name="rawHTML">
<optional>
<!-- If not specified, the default value is 'false'. -->
Expand Down
10 changes: 6 additions & 4 deletions cmake/modules/AddSwift.cmake
View file
Original file line number Diff line number Diff line change
Expand Up @@ -916,6 +916,9 @@ function(_add_swift_library_single target name)
if("${dep}" MATCHES "^clang")
set(dep "${LLVM_LIBRARY_OUTPUT_INTDIR}/lib${dep}.a")
endif()
if("${dep}" STREQUAL "cmark")
set(dep "${CMARK_LIBRARY_DIR}/lib${dep}.a")
endif()
list(APPEND prefixed_link_libraries "${dep}")
endforeach()
set(SWIFTLIB_SINGLE_LINK_LIBRARIES "${prefixed_link_libraries}")
Expand Down Expand Up @@ -1017,12 +1020,11 @@ function(_add_swift_library_single target name)
string(REPLACE ";" " " c_compile_flags "${c_compile_flags}")
string(REPLACE ";" " " link_flags "${link_flags}")


# Set compilation and link flags.
set_property(TARGET "${target}" APPEND_STRING PROPERTY
COMPILE_FLAGS " ${c_compile_flags}")
set_property(TARGET "${target}" APPEND_STRING PROPERTY
LINK_FLAGS " ${link_flags} -L${SWIFT_NATIVE_SWIFT_TOOLS_PATH}/../lib/swift/${SWIFTLIB_SINGLE_SUBDIR} -L${SWIFT_NATIVE_SWIFT_TOOLS_PATH}/../lib/swift/${SWIFT_SDK_${SWIFTLIB_SINGLE_SDK}_LIB_SUBDIR} -L${SWIFTLIB_DIR}/${SWIFTLIB_SINGLE_SUBDIR}")
LINK_FLAGS " ${link_flags} -L${SWIFT_NATIVE_SWIFT_TOOLS_PATH}/../lib/swift/${SWIFTLIB_SINGLE_SUBDIR} -L${SWIFT_NATIVE_SWIFT_TOOLS_PATH}/../lib/swift/${SWIFT_SDK_${SWIFTLIB_SINGLE_SDK}_LIB_SUBDIR} -L${SWIFTLIB_DIR}/${SWIFTLIB_SINGLE_SUBDIR}")
target_link_libraries("${target}" PRIVATE
${SWIFTLIB_SINGLE_PRIVATE_LINK_LIBRARIES})
if(${SWIFTLIB_SINGLE_INTERFACE_LINK_LIBRARIES})
Expand All @@ -1037,7 +1039,7 @@ function(_add_swift_library_single target name)
set_property(TARGET "${target_static}" APPEND_STRING PROPERTY
COMPILE_FLAGS " ${c_compile_flags}")
set_property(TARGET "${target_static}" APPEND_STRING PROPERTY
LINK_FLAGS " ${link_flags} -L${SWIFT_NATIVE_SWIFT_TOOLS_PATH}/../lib/swift/${SWIFTLIB_SINGLE_SUBDIR} -L${SWIFT_NATIVE_SWIFT_TOOLS_PATH}/../lib/swift/${SWIFT_SDK_${SWIFTLIB_SINGLE_SDK}_LIB_SUBDIR} -L${SWIFTSTATICLIB_DIR}/${SWIFTLIB_SINGLE_SUBDIR}")
LINK_FLAGS " ${link_flags} -L${SWIFT_NATIVE_SWIFT_TOOLS_PATH}/../lib/swift/${SWIFTLIB_SINGLE_SUBDIR} -L${SWIFT_NATIVE_SWIFT_TOOLS_PATH}/../lib/swift/${SWIFT_SDK_${SWIFTLIB_SINGLE_SDK}_LIB_SUBDIR} -L${SWIFTSTATICLIB_DIR}/${SWIFTLIB_SINGLE_SUBDIR}")
target_link_libraries("${target_static}" PRIVATE
${SWIFTLIB_SINGLE_PRIVATE_LINK_LIBRARIES})
endif()
Expand Down Expand Up @@ -1692,7 +1694,7 @@ function(add_swift_llvm_loadable_module name)
"${CMAKE_BUILD_TYPE}"
"${LLVM_ENABLE_ASSERTIONS}"
c_compile_flags)

set(link_flags)
_add_variant_link_flags(
"${sdk}"
Expand Down
Loading

0 comments on commit ca5876a

Please sign in to comment.