恩吉的文件和文献¶
良好的文档是高质量理解和使用代码的关键。 Julia 语言可以让您轻松使用和创建开箱即用的文档。
本手册将介绍
- 在.ngscript中获取帮助
- 在命令行中获取帮助
- 为
- 函数
- 全局变量
- 结构
- 模块
还将考虑创建和连接自己的模块的方法。
获取 .ngscript 帮助¶
要在.ngscript中获取帮助，需要使用宏
@doc
考虑获取sqrt.ngscript 的帮助。
注意在文档中使用 *Markdown、$\LaTeX$ 和语法高亮。
@doc sqrt
创建自己的文档¶
"Краткое описание функции, здоровающейся с пользователем"
function user_greeting(username::String)
return "Hello, $(username)!"
end
@doc user_greeting
让我们简要考虑一下为什么需要使用\ 和 $ мы используем raw - литерал необработанных строк:
В LaTex мы используем $\nu$ для обозначения символа ню: $\nu$
Здесь сразу может возникнуть множество проблем. Внутри " "
因此。 "$\nu$"将无法正确执行。不过，这个问题可以通过使用raw-strings 来解决
# "$\nu$" # вызовет ошибки
@show raw"$\nu$";
@doc raw"""
Документация, содержащая:
1. Markdown:
- маркеры списка
- [внешние ссылки](https://engee.com/helpcenter/stable/ru/julia/stdlib/Markdown.html)
2. Встроенный $\LaTeX$ (inline) $\frac{\sqrt{\pi}}{2}$ и отдельной формулой:
```math
\int \limits_{-\infty}^\infty e^{-x^2}\,dx = \sqrt{\pi}
```
## Смотреть также
[`документирование`](https://engee.com/helpcenter/stable/ru/julia/manual/documentation.html
), [`функции`](https://engee.com/helpcenter/stable/ru/julia/manual/functions.html)
"""
function foo()
return nothing
end
@doc foo
记录全局变量¶
"Ускорение свободного падения"
g_Earth, g_Moon
const g_Earth::Float64 = 9.81
const g_Moon::Float64 = 1.62
现在，让我们检查一下两个变量是否同时存在相同的帮助：
@doc g_Earth
@doc g_Moon
请注意，const 意味着变量类型的恒定性，而不是变量值的恒定性。
- 如果类型发生变化，将调用ERROR。
- 当变更为相同类型的值时，将调用警告。
# g_Moon = "Moon"
println(g_Earth)
g_Earth = 32.
println(g_Earth)
问题是如何在平面上以最紧凑的方式排列这些图形。那么结构将包含图形相对于水平面的质量中心和旋转角度。
作为 @doc """
GeometricShape((x=X,y=Y),α)
Геометрическая фигура
- `center_of_mass`: (x=X,y=Y) - кортеж координат центра масс
- `orientation`: α - угол поворота фигуры относительно горизонтали
## Пример:
GeometricShape((x=1., y=2.), 3.)
## Возможные ошибки
1.
```julia-repl
julia> GeometricShape((4.,5.),6.)
ERROR: MethodError: no method matching GeometricShape(::Tuple{Float64, Float64}, ::Float64)
Closest candidates are:
GeometricShape(::@NamedTuple{x::Float64, y::Float64}, ::Any)
```
**Решение:** в кортеже нужно явно указать имена полей: `GeometricShape((x=4., y=5.), 6.)`
2.
```julia-repl
julia> GeometricShape((x=1,y=2),3.)
ERROR: MethodError: no method matching GeometricShape(::@NamedTuple{x::Int64, y::Int64}, ::Float64)
Closest candidates are:
GeometricShape(::@NamedTuple{x::Float64, y::Float64}, ::Any)
```
**Решение:** передавайте в качетсве параметров значения типа `Float64`, а не `Int64`: GeometricShape((x=1.,y=2.),3.)
"""
struct GeometricShape
center_of_mass::NamedTuple{(:x,:y),Tuple{Float64,Float64}}
orientation::Float64
GeometricShape() = new((x=0,y=0),0) # конструктор по умолчанию
GeometricShape((X,Y)::NamedTuple{(:x,:y),Tuple{Float64,Float64}},α)=new((x=X,y=Y),α)
end
GeometricShape((x=4.,y=5.),6.)
@doc GeometricShape
GeometricShape()
first_shape = GeometricShape((x=1.,y=2.),3.)
first_shape.center_of_mass.y
请注意，我们结构中的对象在构造后是不可变的。如果需要使用可变对象，它们必须是 mutable struct 类型。
# first_shape.orientation = 4. # ОШИБКА: нельзя менять уже созданный объект
记录宏¶
"Макрос, здоровающийся с пользователем"
macro hellouser(username) # создание макроса
println("Hello, $(username)!")
end
@hellouser "Peter" # применение макроса
要获取宏的帮助，必须先编写@ ，然后输入宏名：
@macrosname
@doc @hellouser
创建和记录模块¶
在本示例的文件夹中有一个 TemperatureScales.jl 文件。该文件包含模块TemperatureScales 。
要访问其函数和变量，您需要
1.使用命令cd(path) 进入文件夹，可执行文件 (documentating.ngscript) (@__DIR__) 位于该文件夹。同一路径包含 TemperatureScales.jl：
@__DIR__
cd(@__DIR__)
2.将该模块包含在脚本中：
执行命令include("Filename.jl") 后，julia 会将文件Filename.jl 中的文本 "包含 "到当前脚本中并执行。(请看文件TemperatureScales.jl 的第一行）。这意味着该文件中的对象将成为我们文件中的对象。
include("TemperatureScales.jl")
println(variable_from_TemperatureScales)
但我们的任务是使用该文件中的模块。使用关键字module 创建模块，使用关键字using 或import 使用模块。
using .TemperatureScales
要了解该模块的具体功能，让我们调用模块帮助：
@doc TemperatureScales
让我们来了解一下 fahr2cels 功能是如何工作的：
@doc fahr2cels
正如您所看到的，fahr2cels 帮助说明了两种方法。第一种方法适用于参数为数字的情况，第二种方法适用于参数为字符串的情况。
现在进入命令提示符并运行
fahr2cels
注意最后一行：
扩展帮助可从?? 获取。
现在退出帮助模式（删除?)
现在输入
??fahr2cels
现在我们有一个扩展的引用 😊😊😊😊。