[轉貼] JSDoc 及 PHPDocument 註解撰寫差異

本篇文章轉貼自：林中路 - JSDoc 與 phpDocumentor

JSDoc

@fileoverview : 檔案描述, 鷹置於檔案開始.
@author : 作者. 我寫我, 你寫你.
@version : 指定版本訊息.
@see : 建立一個鏈結，指出相關於的類別描述文件.
@require : 建立一個鏈結，指出必要的類別描述文件.
@deprecated :
@param : 參數說明.
@argument : 引數說明.
@return : 返回值說明.
@throws :
@exception :
@private :
@final : 常數值說明.
@ignore : 忽略此函式.
@class : 類別說明.
@constructor : 初始建構式說明.
@type : 返回值類型說明.
@extends : 繼承說明.

phpDocumentor

@abstract : 抽象類型的標記說明. 使用範圍 method, class variable, class 等.
@access : 標記可駐明關鍵字的存取權限：private、public 或 proteced. 使用範圍 class, function, var, define, module 等.
@author : 作者. 我寫我, 你寫你.
@category :
@copyright : 版權註解, 使用範圍 class, function, var, define, module, use 等.
@deprecated : 棄用標示, 使用範圍 class, function, var, define, module, constent, global, include 等.
@example : 高亮顯示註解文字段落,
@const : 標示定義的常量, 使用範圍 define.
@final : 完成, 可用來標明此關鍵字為最終的完成狀態 (有些文件說可以禁止派生與修改, 這可能嗎?). 使用範圍 class, function, var 等.
@filesource : 類似 example, 直接讀取當前解析的php文件的內容並顯示.
@global : 全局變量.
@ingore : 忽略指定的關鍵字.
@license : 標記授權 URL 與內容.
@link : 類似 @license, 作用就如 html 相似.
@name : 名稱註解.
@package :
@param : 函數的引數或參數說明.
@return : 返回值或狀態說明.
@see : 參考連結.
@since :
@static :
@staticvar : 靜態說明.
@subpackage :
@var datatype description : 變數與變數類型說明.
@todo information string [unspecified format] : 功能規劃性遞變說明.
@uses file.ext|elementname|class::methodname()|class::$variablename|functionname()|function functionname description of how the element is used : 使用方式說明
@version : versionstring [unspecified format], 版本說明.

留言

這個網誌中的熱門文章

npm 還可以看影片，沒想到真的有人這麼做

還真的有人做這件事情，庆余年2剛上線，有一位小哥竟然利用 npm 包的機制，將整套高清視頻都搬上來了。 https://x.com/fengmk2/status/1791498406923215020 圖片來源， https://x.com/fengmk2/status/1791498406923215020/photo/1 此 Package 出處 https://www.npmjs.com/package/lyq2?activeTab=versions 截圖留念，機制說明 NPM（Node Package Manager）是一個流行的 JavaScript 軟件包管理器，用於管理和分發 Node.js 應用的依賴。它允許開發者將自己的代碼打包成「包」，並上傳到 NPM 的公共註冊表，供其他開發者下載和使用。這個過程通常包括以下步驟：創建 NPM 包：開發者將自己的代碼和相關文件打包成一個 NPM 包。上傳到註冊表：將包上傳到 NPM 的公共註冊表。下載和使用：其他開發者可以通過 NPM 命令行工具下載並安裝這些包。這位小哥利用這一機制，可能是通過將整套高清視頻文件打包成 NPM 包並上傳到公共註冊表。其他人只需通過簡單的 NPM 命令即可下載這些視頻文件。影響版權問題：這種行為涉及明顯的版權侵犯。高清視頻通常受到版權保護，未經授權的分發和下載都是非法的。 NPM 註冊表的可靠性：這類內容的出現可能會損害 NPM 註冊表的可靠性和聲譽。NPM 註冊表是開發者分享和使用代碼的重要平台，如果充斥著這些不合法的內容，會影響其公信力。潛在的安全風險：將視頻文件偽裝成 NPM 包可能會帶來潛在的安全風險。下載這些包的用戶可能會無意中下載到惡意軟件或其他有害內容。技術濫用：這一行為展示了技術的濫用，原本為了方便開發者分享和使用代碼的機制，被用來分發非法內容，會對整個開發者社區造成負面影響。歡迎留言給我，讓我們得到更多討論，一起回饋更多可能。如果對於技術架構或者技術開發有相關需要顧問教育訓練服務或專案開發，聯絡方式如下，或者是與皇漢科技 EXMA-Square 進行聯繫。 FB: https://www.facebook.com/clonncd/ Twitter: https://twitter.com/clonncd 熱血漢誌: htt

繼續閱讀>>

Redis 已經不再免費了嗎？Redis is no longer free software ?

根據Redis Source Available License 2.0 (RSALv2)的條款，這份授權協議提供了一定程度的使用、複製、分發、使其可用、以及創建衍生作品的自由，但這些自由受到特定限制，特別是關於將軟體功能作為服務提供給第三方或分發軟體的方式，這可能限制了軟體的自由共享和再分發。根據自由軟體基金會（Free Software Foundation, FSF）和開源倡議組織（Open Source Initiative, OSI）定義的自由軟體和開源軟體的標準，一個軟體要被認為是“自由軟體”或“開源軟體”，它需要允許用戶在任何目的下運行軟體、研究和修改軟體、以及自由地重新分發複製品，有時還包括創建和分發衍生作品的自由。 RSALv2設置了一些重要的使用和分發限制，特別是關於禁止將軟體或其修改版本作為服務提供給第三方的限制，這可能不符合FSF和OSI對自由軟體或開源軟體的定義。這些限制主要是為了保護Redis Ltd.的商業利益，同時允許使用者在某些條件下使用和修改軟體。因此，雖然RSALv2提供了一些使用和修改軟體的自由，但它由於上述限制，可能不會被廣泛認定為符合“自由軟體”或“開源軟體”的嚴格定義。它更像是一種介於傳統封閉源代碼軟體和開放源碼軟體之間的“源可用”授權模式。主觀想法怎麼開源的狀態下還是需要商業利益的支持，只有在商業模式下才能走得長久，這段協議會影響到的基本上三大公有雲 Azure / AWS / Google Cloud Platform 絕對首當其衝，但如果以服務提供商的角色，能夠跟這樣的開源坐下來好好談談，也許這樣的 Agreement 可能對於 Redis 後續的生態發展才會是好的方式？就讓我們持續看下去！ Ref: https://lwn.net/Articles/966133/ https://redis.com/blog/redis-adopts-dual-source-available-licensing/ https://redis.com/legal/rsalv2-agreement/

繼續閱讀>>

CSS Animation 救星？Apple 推出 Keyframer，讓 LLM 大型語言模型產生動畫

CSS Animation 救星？Apple 推出 Keyframer，讓 LLM 大型語言模型產生動畫 Apple 釋出 Keyframer 工具利用大型語言模型（LLMs）來為靜態圖像（SVG格式）創造動畫。透過與專業動畫設計師和工程師的訪談，Keyframer 支援通過提示和直接編輯生成的輸出來探索和精煉動畫。此系統還允許用戶請求設計變體，支持比較和創意發想。包括用於描述運動的語義提示類型的分類和一種“分解式”提示風格，其中用戶不斷根據生成的輸出調整他們的目標。分享了如何通過直接編輯以及提示來實現超越當今生成工具中常見的一次性提示界面的迭代。通過這項工作，提出了LLMs 可能如何賦能廣泛的觀眾群體參與動畫創作。對於網頁開發者或設計師，Keyframer提供了以下潛在的幫助和用途：創意表達的擴展：開發者和設計師可以使用自然語言描述來創造或修改動畫，這樣可以快速實驗和實現創意想法，而無需深入複雜的動畫程式碼或工具。高效的設計流程：通過結合語言提示和直接編輯，使用者可以迅速探索動畫設計的不同變體，加速從概念到原型的過程。動畫設計的無障礙化：即使是沒有動畫背景的開發者和設計師也能輕鬆入門，透過自然語言的引導創造動感豐富的界面和視覺效果。促進創意發想和迭代：Keyframer支持設計思維的迭代過程，讓使用者能夠不斷優化和細化他們的動畫設計，促進創意的深入發展。個性化和定制動畫：用戶可以請求特定的設計變體，以滿足特定項目的需求或遵循品牌指南，從而創建更加個性化和定制化的動畫效果。 Keyframer為網頁開發者和設計師提供了一種全新的與動畫互動和創造的方式，使他們能夠更加自由地探索和實現創意視覺效果，從而提升用戶體驗和網站的吸引力。

繼續閱讀>>

熱血漢誌 - 技術新鮮人到技術經理人，必懂的事

搜尋此網誌