Merge pull request #3485 from ezz666/ldoc_readonly_tag

Ldoc readonly tag

docs/config.ld

@@ -466,7 +466,7 @@ add_custom_tag {
     auto_subtags = false
 }
 
--- Mark the item ad hidden.
+-- Mark the item as hidden.
 -- This tag should be used to hide items from the documentation.
 -- @hidden
 add_custom_tag {
@@ -475,6 +475,14 @@ add_custom_tag {
     auto_subtags = false
 }
 
+-- Mark the item as readonly.
+-- This tag should be used to mark readonly properties.
+-- @readonly
+add_custom_tag {
+    name = "readonly",
+    hidden = true,
+    auto_subtags = false
+}
 -- More fitting section names
 kind_names={topic='Documentation', module='Libraries', script='Sample files'}
 
@@ -635,6 +643,9 @@ local function generate_summary(item)
             has_show_more = v.showcount or has_show_more
         end
     end
+    if item.tags.readonly then
+        ret[#ret+1] = {title = "read only"}
+    end
 
     item.extra_summary = #ret > 0 and ret or nil
     item.has_show_more = has_show_more

docs/ldoc.css

@@ -342,6 +342,16 @@ span.inheritance {
     text-align: right;
 }
 
+span.chips--readonly {
+  border: 1px solid #9db9f3;
+  border-radius: 25px;
+  padding: 1px 3px;
+  font-size: 70%;
+  color: #9db9f3;
+  background-color: #FFF;
+  margin-left: 10px;
+}
+
 table.function_list .function_args /*.function_modname*/ {
     color: #94b1ff;
     text-decoration: underline;

docs/ldoc.ltp

@@ -292,7 +292,12 @@
 #     end
       </td>
 #   end
-      <td colspan="$(inherited and 1 or 2)" class="summary">$(M(item.summary,item))</td>
+      <td colspan="$(inherited and 1 or 2)" class="summary">
+        $(M(item.summary,item))
+#   if item.tags.readonly then
+        <span class="chips--readonly">read only</span>
+#   end
+      </td>
 #   if inherited then
       <td class="baseclass" nowrap>
         Inherited from $(item.baseclass)

lib/awful/client.lua

@@ -850,10 +850,10 @@ end
 
 --- Return if a client has a fixed size or not.
 --
--- This property is read only.
 -- @property is_fixed
 -- @tparam[opt=false] boolean is_fixed The fixed size state
 -- @propemits false false
+-- @readonly
 -- @see size_hints
 -- @see size_hints_honor
 
@@ -876,9 +876,9 @@ end
 -- Does the client have a fixed horizontal position and width, i.e. is it
 -- fullscreen, maximized, or horizontally maximized?
 --
--- This property is read only.
 -- @property immobilized_horizontal
 -- @tparam[opt=false] boolean immobilized_horizontal The immobilized state
+-- @readonly
 -- @see maximized
 -- @see maximized_horizontal
 -- @see fullscreen
@@ -892,9 +892,9 @@ end
 -- Does the client have a fixed vertical position and width, i.e. is it
 -- fullscreen, maximized, or vertically maximized?
 --
--- This property is read only.
 -- @property immobilized_vertical
 -- @tparam[opt=false] boolean immobilized_vertical The immobilized state
+-- @readonly
 -- @see maximized
 -- @see maximized_vertical
 -- @see fullscreen
@@ -1757,6 +1757,7 @@ pcommon.setup_grant(client.object, "client")
 -- @tparam boolean active
 -- @request client border active granted When a client becomes active.
 -- @request client border inactive granted When a client stop being active.
+-- @readonly
 -- @see activate
 -- @see request::activate
 -- @see awful.permissions.add_activate_filter

lib/awful/screen.lua

@@ -181,7 +181,7 @@ end
 
 --- The area where clients can be tiled.
 --
--- This property holds the (read only) area where clients can be tiled. Use
+-- This property holds the area where clients can be tiled. Use
 -- the `padding` property, `wibox.struts` and `client.struts` to modify this
 -- area.
 --
@@ -193,6 +193,7 @@ end
 -- @tparam number tiling_area.y
 -- @tparam number tiling_area.width
 -- @tparam number tiling_area.height
+-- @readonly
 -- @see padding
 -- @see get_bounding_geometry
 
@@ -205,11 +206,12 @@ end
 
 --- Take a screenshot of the physical screen.
 --
--- Reading this (read only) property returns a screenshot of the physical
+-- Reading this property returns a screenshot of the physical
 -- (Xinerama) screen as a cairo surface.
 --
 -- @property content
 -- @tparam gears.surface content
+-- @readonly
 
 function screen.object.get_content(s)
     local geo = s.geometry
@@ -301,7 +303,6 @@ end
 --
 --  * *property::outputs*
 --
--- **Immutable:** true
 -- @property outputs
 -- @param table
 -- @tfield table table.name A table with the screen name as key (like `eDP1` on a laptop)
@@ -310,6 +311,7 @@ end
 -- @tfield integer table.name The output name.
 -- @tfield integer table.viewport_id The identifier of the viewport this output
 --  corresponds to.
+-- @readonly
 
 function screen.object.get_outputs(s)
     local ret = {}
@@ -555,12 +557,13 @@ end
 
 --- A list of all tags on the screen.
 --
--- This property is read only, use `tag.screen`, `awful.tag.add`,
+-- Use `tag.screen`, `awful.tag.add`,
 -- `awful.tag.new` or `t:delete()` to alter this list.
 --
 -- @property tags
 -- @param table
 -- @treturn table A table with all available tags.
+-- @readonly
 
 function screen.object.get_tags(s, unordered)
     local tags = {}
@@ -584,6 +587,7 @@ end
 -- @property selected_tags
 -- @param table
 -- @treturn table A table with all selected tags.
+-- @readonly
 -- @see tag.selected
 -- @see client.to_selected_tags
 
@@ -603,6 +607,7 @@ end
 -- @property selected_tag
 -- @param tag
 -- @treturn ?tag The first selected tag or nil.
+-- @readonly
 -- @see tag.selected
 -- @see selected_tags
 
@@ -753,10 +758,12 @@ end
 --- The lowest density DPI from all of the (physical) outputs.
 -- @property minimum_dpi
 -- @param number the DPI value.
+-- @readonly
 
 --- The highest density DPI from all of the (physical) outputs.
 -- @property maximum_dpi
 -- @param number the DPI value.
+-- @readonly
 
 --- The preferred DPI from all of the (physical) outputs.
 --
@@ -765,6 +772,7 @@ end
 --
 -- @property preferred_dpi
 -- @param number the DPI value.
+-- @readonly
 
 --- The maximum diagonal size in millimeters.
 --

objects/client.c

@@ -449,6 +449,7 @@ lua_class_t client_class;
  * @property window
  * @tparam integer window
  * @propemits false false
+ * @readonly
  */
 
 /**
@@ -522,6 +523,7 @@ lua_class_t client_class;
  * @property type
  * @tparam string type
  * @propemits false false
+ * @readonly
  * @see ruled.client
  */
 
@@ -550,6 +552,7 @@ lua_class_t client_class;
  * @property class
  * @tparam string class
  * @propemits false false
+ * @readonly
  * @see instance
  * @see ruled.client
  */
@@ -576,6 +579,7 @@ lua_class_t client_class;
  * @property instance
  * @tparam string instance
  * @propemits false false
+ * @readonly
  * @see class
  * @see ruled.client
  */
@@ -588,6 +592,7 @@ lua_class_t client_class;
  * @property pid
  * @tparam integer pid
  * @propemits false false
+ * @readonly
  */
 
 /**
@@ -596,6 +601,7 @@ lua_class_t client_class;
  * @property role
  * @tparam string role
  * @propemits false false
+ * @readonly
  * @see instance
  * @see class
  */
@@ -616,6 +622,7 @@ lua_class_t client_class;
  * @property machine
  * @tparam string machine
  * @propemits false false
+ * @readonly
  */
 
 /**
@@ -624,6 +631,7 @@ lua_class_t client_class;
  * @property icon_name
  * @tparam string icon_name
  * @propemits false false
+ * @readonly
  */
 
 /**
@@ -670,6 +678,7 @@ lua_class_t client_class;
  * @property icon_sizes
  * @tparam table sizes
  * @propemits false false
+ * @readonly
  * @see awful.widget.clienticon
  * @see get_icon
  */
@@ -912,6 +921,7 @@ lua_class_t client_class;
  *
  * @property content
  * @tparam surface content
+ * @readonly
  * @see gears.surface
  */
 
@@ -1048,6 +1058,7 @@ lua_class_t client_class;
  * @property transient_for
  * @tparam client transient_for
  * @propemits false false
+ * @readonly
  * @see modal
  * @see type
  * @see is_transient_for
@@ -1064,6 +1075,7 @@ lua_class_t client_class;
  * @property group_window
  * @tparam integer group_window
  * @propemits false false
+ * @readonly
  * @see leader_window
  */
 
@@ -1075,6 +1087,7 @@ lua_class_t client_class;
  * @property leader_window
  * @tparam number leader_window
  * @propemits false false
+ * @readonly
  * @see transient_for
  * @see modal
  * @see group_window
@@ -1127,6 +1140,7 @@ lua_class_t client_class;
  * @tparam[opt] integer|nil hints.base_width
  * @tparam[opt] integer|nil hints.base_height
  * @propemits false false
+ * @readonly
  * @see size_hints_honor
  * @see geometry
  */
@@ -1162,6 +1176,7 @@ lua_class_t client_class;
  *  `full_application_modal` or `unknown`.
  * @tparam[opt] boolean hints.status.tearoff_window
  * @propemits false false
+ * @readonly
  */
 
 /**
@@ -1283,6 +1298,7 @@ lua_class_t client_class;
  * @property client_shape_bounding
  * @tparam surface client_shape_bounding
  * @propemits false false
+ * @readonly
  * @see shape_bounding
  * @see shape_clip
  * @see shape_input
@@ -1299,6 +1315,7 @@ lua_class_t client_class;
  * @property client_shape_clip
  * @tparam surface client_shape_clip
  * @propemits false false
+ * @readonly
  * @see shape_bounding
  * @see shape_clip
  * @see shape_input
@@ -1379,6 +1396,7 @@ lua_class_t client_class;
  * @property valid
  * @tparam boolean valid
  * @propemits false false
+ * @readonly
  * @see kill
  */
 
@@ -1392,6 +1410,7 @@ lua_class_t client_class;
  * @property first_tag
  * @tparam tag first_tag
  * @propemits false false
+ * @readonly
  * @see tags
  */
 

objects/screen.c

@@ -171,8 +171,6 @@
  *
  *  * *property::geometry*
  *
- * **Immutable:** true
- *
  * @DOC_screen_geometry_EXAMPLE@
  *
  * @property geometry
@@ -181,6 +179,7 @@
  * @tfield integer table.y The vertical position
  * @tfield integer table.width The width
  * @tfield integer table.height The height
+ * @readonly
  */
 
 /**
@@ -208,10 +207,10 @@
  *
  *     screen[1].answer = 42
  *
- * **Immutable:** true
  * @property index
  * @param integer
  * @see screen
+ * @readonly
  */
 
 /**
@@ -236,6 +235,7 @@
  * @tfield integer table.y The vertical position
  * @tfield integer table.width The width
  * @tfield integer table.height The height
+ * @readonly
  */