2024年3月13日发(作者：)
源代码说明文档范文
参考：
这种说明性文档一般是使用Text Macros来做的
Text Macros一般被翻译为文本宏，它是Xcode隐藏的特性，XCode 9.0后，Apple
允许开发者进行自定义文本宏。 文本宏（Text Macro）是一种可以就地展开
（expanded in-place）为特定文本的符号。其常见于Xcode文件模板中.
Xcode在使用文件模板创建文件时，会把文件模板中的文本宏，展开生成特定的文
本，比如如使用NSObjectObjective-C文件模板创建一个文件名为MyObject.m的
文件时，FILEHEADER会展开生成头部注释信息，FILEBASENAME会展开生成字
符串MyObject，FILEBASENAMEASIDENTIFIER会展开生成字符串MyObject
Xcode模板有文件模板和工程模板。模板文件按照开发平台存放，其中每个平台的
模板位置如下：
•
•
macOS平台模板：
/Applications//Contents/Developer/Library/Xcode/Templates
iOS平台模板：
/Applications//Contents/Developer/Platforms/r
m/Developer/Library/Xcode/Templates
tvOS平台板：
/Applications//Contents/Developer/Platforms/
rm/Developer/Library/Xcode/Templates
watchOS平台模板：
/Applications//Contents/Developer/Platforms/rm
/Developer/Library/Xcode/Templates
•
•
举个例子： 通过XCode建立一个基于Objective-C项目，名为TextMacrosDemo，
建立一个Person类，生成了Person.h和Person.m这两个文件：
查看文件模板：
$ open /Applications//Contents/Developer/Platforms/r
m/Developer/Library/Xcode/
打开 ___FILEBASENAME___.h会看到：
而___FILEBASENAME___.m对应：
XCode 就是根据文件模板创建的文件，在文件模板中就是使用的文本宏Text
Macros. 假如我们在___FILEBASENAME___.m里添加一些代码：
新建类Hello，可见Hell.m内容为：
一般做法
在源代码文件头部加上一些信息说明，不推荐上面那种直接修改模板文件。一般是
新建名为的文件并放入相应位置，比如：
由于添加了字段：FILEHEADER：The text placed at the top of every new text file.
t> 写好后需要把此文件放入相应位置： • • • • • 只修改 project 中 唯独你 所创建的文件: 修改 project 中 所有人 创建的文件: 修改 worksspace 中 唯独你 所创建的文件: 修改 worksspace 中 所有人 所创建的文件: 修改此电脑上 Xcode 所创建的 所有文件: ~/Library/Developer/Xcode/UserData/ 右键roj > 显示包内容 > 右键space > 显示包内容 > xcshareddata > 放入文件，这样当新建比如： 文件时，可以看到头文件生成了： ///******************************************************************************** ******* // * // * Project: Demo // * // * Copyright © 2023-2023 大刘 Technol ogies Co.,Ltd // * All rights reserved. // * // * This software is supplied onl y under the terms of a license agreement, // * nondisclosure agreement or other wr itten agreement with 大刘 Technologies // * Co.,Ltd. Use, redistribution or other dis closure of any parts of this // * software is prohibited except in accordance with the terms of such written // * agreement with 大刘 Technologies Co.,Ltd. This software is confidential // * and proprietary information of 大刘 Technologies Co.,Ltd. // * / / ********************************************************************************** ***** // * // * Header Name: // * // * General Description: Copyright a nd file header. // * // * Created by 大刘 on 2023/1/15. // * // ********************* *******************************************************************/ 格式化文本宏的值 一个text macro可以包含任意合法的unicode文本，它也可以包含另一个text macros，如果要包含其他text macro, 需要在这个宏的前和后分别加上三个英文下 划线___，比如：___FILENAME___ 也可以通过添加修饰符修改宏文本，文本宏和修 饰符之间用分号（:）分隔。多个修饰符之间可以用逗号（,）分隔。 格式： ___FILENAME___ 被替换为 ___FILENAME:deletingPathExtension___ 被 替换为Person 增加文本宏 只需要增加key-value即可： 给创建的类都添加统一前缀 这时候使用Xcode创建的一个类时，类的前缀都是以DL开头 公开可用的文本宏 • 时间类 – DATE 当前的日期，如2023/12/20 – YEAR 四位数字格式的当前年数，如2023 – TIME 当前的时间，如20:48 • 开发环境类 – RUNNINGMACOSVERSION 当前macOS系统的版本 – DEFAULTTOOLCHAINSWIFTVERSION 当前工程使用的Swift版本 – FULLUSERNAME 当前系统用户的全名 – USERNAME 当前macOS用户的登录名 • 开发工程配置类 – ORGANIZATIONNAME 当前工程配置的公司名称 – WORKSPACENAME 当前Workspace的名称。如果Workspace中只 有一个 Project，那么这个宏的值便是当前打开的Project的名称 – PROJECTNAME 当前工程的名称 – PACKAGENAME 当前工程Scheme所设置的包名 – PACKAGENAMEASIDENTIFIER 把不符合C语言标识符规范的字符替 换为下划线（_）后的PACKAGENAME – PRODUCTNAME 当前工程Scheme设置的应用名称 COPYRIGHT 当前工程的版权信息，如Copyright © 2023 DL-Unit. All rights reserved.。需要注意的是，若当前Xcode工程没有配置公司名， 该值会是一个空字符串 • 文本文件信息类 – FILENAME 当前文件的完整名称，包括扩展名 – FILEBASENAME 删除掉扩展名后的FILENAME，如创建一个名为 MyObject.m的文件，该值为MyObject – FILEBASENAMEASIDENTIFIER 把不符合C语言标识符规范的字符替 换为下划线（）后的FILEBASENAME，如创建一个名为My-Object.m 的文件，该值为My_Object 注：C语言标识符规范只允许使用字母 （A-Z, a-z）和数字（0-9）以及下划线（），使用这个宏会把其他的 字符自动替换成下划线 – FILEHEADER 每个文本文件头部的文本. 注：该文本宏其实是由多个 文本宏组成，其首先是展开生成以下文本 // ___FILENAME___ // ___PACKAGENAME___ // // Created by ___FULLUSERNAME__ _ on ___DATE___. // ___COPYRIGHT___ // 之后Xcode再把上述的宏文本展开生成对应的文本，最后生成的就是我们日常看 到的文件头部注释信息了 其他 – UUID 使用这个宏的时候，会返回一个唯一ID。具体应用场景待探索。 – NSHUMANREADABLECOPYRIGHTPLIST target中的 文件中 人类可读的版权信息条目的值，该值包括这个条目的key和value以 及XML的分隔符, 如： rights reserved. 一个示例 • –
发布评论